docs: update api-docs

Author: kikuomax

api-docs/cdk-rest-api-with-spec.api.md

@@ -18,27 +18,18 @@ export interface IAuthorizerWithSpec extends aws_apigateway.IAuthorizer {
     securitySchemeObject?: SecuritySchemeObject;
 }
 
-// @beta
-export interface IBaseResourceWithSpec extends aws_apigateway.IResource {
-    addMethod(httpMethod: string, target?: aws_apigateway.Integration, options?: MethodOptionsWithSpec): aws_apigateway.Method;
-    addResource(pathPart: string, options?: ResourceOptionsWithSpec): IResourceWithSpec;
-    defaultMethodOptions?: MethodOptionsWithSpec;
-    parentResource?: IBaseResourceWithSpec;
-}
-
 // @beta
 export interface IResourceWithSpec extends aws_apigateway.Resource {
     addMethod(httpMethod: string, target?: aws_apigateway.Integration, options?: MethodOptionsWithSpec): aws_apigateway.Method;
     addResource(pathPart: string, options?: ResourceOptionsWithSpec): IResourceWithSpec;
     defaultMethodOptions?: MethodOptionsWithSpec;
-    parentResource?: IBaseResourceWithSpec;
+    parentResource?: IResourceWithSpec;
 }
 
 // @beta
-export interface IRestApiWithSpec extends aws_apigateway.RestApi {
+export interface IRestApiWithSpec extends aws_apigateway.IRestApi {
     addModel(id: string, props: ModelOptionsWithSpec): aws_apigateway.Model;
-    root: IBaseResourceWithSpec;
-    underlying: aws_apigateway.RestApi;
+    readonly root: IResourceWithSpec;
 }
 
 // @beta
@@ -109,18 +100,16 @@ export interface ResourceOptionsWithSpec extends aws_apigateway.ResourceOptions
 }
 
 // @beta
-export type RestApiFactory = (scope: Construct, id: string, props?: aws_apigateway.RestApiProps) => aws_apigateway.RestApi;
-
-// @beta
-export class RestApiWithSpec {
-    static createRestApi(scope: Construct, id: string, props: RestApiWithSpecProps): IRestApiWithSpec;
+export class RestApiWithSpec extends aws_apigateway.RestApi implements IRestApiWithSpec {
+    constructor(scope: Construct, id: string, props: RestApiWithSpecProps);
+    addModel(id: string, props: ModelOptionsWithSpec): aws_apigateway.Model;
     // (undocumented)
     readonly props: RestApiWithSpecProps;
+    readonly root: IResourceWithSpec;
 }
 
 // @beta
 export interface RestApiWithSpecProps extends aws_apigateway.RestApiProps {
-    newRestApi?: RestApiFactory;
     openApiInfo: Partial<InfoObject> & Pick<InfoObject, 'version'>;
     openApiOutputPath: string;
 }

api-docs/markdown/cdk-rest-api-with-spec.ibaseresourcewithspec.addmethod.md

@@ -7,7 +7,7 @@
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
 > 
 
-[aws\_apigateway.Resource](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Resource.html) augmented with the features to build the OpenAPI definition.
+[aws\_apigateway.IResource](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.IResource.html) augmented with the features to build the OpenAPI definition.
 
 <b>Signature:</b>
 
@@ -16,12 +16,16 @@ export interface IResourceWithSpec extends apigateway.Resource
 ```
 <b>Extends:</b> apigateway.Resource
 
+## Remarks
+
+Although this interface actually inherits [aws\_apigateway.Resource](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.Resource.html)<!-- -->, you should rely on only properties defined in [aws\_apigateway.IResource](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.IResource.html)<!-- -->.
+
 ## Properties
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
 |  [defaultMethodOptions?](./cdk-rest-api-with-spec.iresourcewithspec.defaultmethodoptions.md) |  | [MethodOptionsWithSpec](./cdk-rest-api-with-spec.methodoptionswithspec.md) | <b><i>(BETA)</i></b> <i>(Optional)</i> Default method options with the OpenAPI definition. |
-|  [parentResource?](./cdk-rest-api-with-spec.iresourcewithspec.parentresource.md) |  | [IBaseResourceWithSpec](./cdk-rest-api-with-spec.ibaseresourcewithspec.md) | <b><i>(BETA)</i></b> <i>(Optional)</i> Parent resource. |
+|  [parentResource?](./cdk-rest-api-with-spec.iresourcewithspec.parentresource.md) |  | [IResourceWithSpec](./cdk-rest-api-with-spec.iresourcewithspec.md) | <b><i>(BETA)</i></b> <i>(Optional)</i> Parent resource. |
 
 ## Methods
 

api-docs/markdown/cdk-rest-api-with-spec.ibaseresourcewithspec.addresource.md

@@ -12,7 +12,7 @@ Parent resource.
 <b>Signature:</b>
 
 ```typescript
-parentResource?: IBaseResourceWithSpec;
+parentResource?: IResourceWithSpec;
 ```
 
 ## Remarks

api-docs/markdown/cdk-rest-api-with-spec.ibaseresourcewithspec.defaultmethodoptions.md

@@ -12,16 +12,15 @@
 <b>Signature:</b>
 
 ```typescript
-export interface IRestApiWithSpec extends apigateway.RestApi 
+export interface IRestApiWithSpec extends apigateway.IRestApi 
 ```
-<b>Extends:</b> apigateway.RestApi
+<b>Extends:</b> apigateway.IRestApi
 
 ## Properties
 
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
-|  [root](./cdk-rest-api-with-spec.irestapiwithspec.root.md) |  | [IBaseResourceWithSpec](./cdk-rest-api-with-spec.ibaseresourcewithspec.md) | <b><i>(BETA)</i></b> Root resource ('/') with the features to build the OpenAPI definition. |
-|  [underlying](./cdk-rest-api-with-spec.irestapiwithspec.underlying.md) |  | apigateway.RestApi | <b><i>(BETA)</i></b> Underlying [aws\_apigateway.RestApi](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_apigateway.RestApi.html) object. |
+|  [root](./cdk-rest-api-with-spec.irestapiwithspec.root.md) | <code>readonly</code> | [IResourceWithSpec](./cdk-rest-api-with-spec.iresourcewithspec.md) | <b><i>(BETA)</i></b> Root resource ('/') with the features to build the OpenAPI definition. |
 
 ## Methods
 

api-docs/markdown/cdk-rest-api-with-spec.ibaseresourcewithspec.md

@@ -12,5 +12,5 @@ Root resource ('/') with the features to build the OpenAPI definition.
 <b>Signature:</b>
 
 ```typescript
-root: IBaseResourceWithSpec;
+readonly root: IResourceWithSpec;
 ```