documentation - 如何使用 aws cdk 记录 rest api

Question

我正在使用 AWS CDK 版本 1.22 创建一个 REST API，我也想使用 CDK 记录我的 API，但我没有看到部署后为我的 API 生成的任何文档。

我已经深入研究了 aws 文档、cdk 示例、cdk 引用，但我可以找到具体示例来帮助我理解如何去做。

这是我的代码:

const app = new App();
const api = new APIStack(app, 'APIStack', { env }); // basic api gateway

// API Resources
const resourceProps: APIResourceProps = {
  gateway: api.gateway,
}

// dummy endpoint with some HTTP methods
const siteResource = new APISiteStack(app, 'APISiteStack', {
  env,
  ...resourceProps
});

const siteResourceDocs = new APISiteDocs(app, 'APISiteDocs', {
  env,
  ...resourceProps,
});

// APISiteDocs is defined as follow:
class APISiteDocs extends Stack {

  constructor(scope: Construct, id: string, props: APIResourceProps) {
    super(scope, id, props);

    new CfnDocumentationVersion(this, 'apiDocsVersion', {
      restApiId: props.gateway.restApiId,
      documentationVersion: config.app.name(`API-${config.gateway.api.version}`),
      description: 'Spare-It API Documentation',
    });

    new CfnDocumentationPart(this, 'siteDocs', {
      restApiId: props.gateway.restApiId,
      location: {
        type: 'RESOURCE',
        method: '*',
        path: APISiteStack.apiBasePath,
        statusCode: '405',
      },
      properties: `
        {
          "status": "error",
          "code": 405,
          "message": "Method Not Allowed"
        }
      `,
    });
  }
}

感谢任何帮助/提示，​​谢谢。

Answer 1

我已经使用 CDK 1.31 进行了测试，可以使用 CDK 的默认部署选项，还可以在舞台上添加文档版本。我在 rest api 定义中使用了 deployOptions.documentVersion 来设置 API 文档的版本标识符:

import * as cdk from '@aws-cdk/core';
import * as apigateway from "@aws-cdk/aws-apigateway";
import {CfnDocumentationPart, CfnDocumentationVersion} from "@aws-cdk/aws-apigateway";

export class CdkSftpStack extends cdk.Stack {
  constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const documentVersion = "v1";

    // create the API
    const api = new apigateway.RestApi(this, 'books-api', {
      deploy: true,
      deployOptions: {
        documentationVersion: documentVersion
      }
    });

    // create GET method on /books resource
    const books = api.root.addResource('books');
    books.addMethod('GET');

    // // create documentation for GET method
    new CfnDocumentationPart(this, 'doc-part1', {
      location: {
        type: 'METHOD',
        method: 'GET',
        path: books.path
      },
      properties: JSON.stringify({
        "status": "successful",
        "code": 200,
        "message": "Get method was succcessful"
      }),
      restApiId: api.restApiId
    });

    new CfnDocumentationVersion(this, 'docVersion1', {
      documentationVersion: documentVersion,
      restApiId: api.restApiId,
      description: 'this is a test of documentation'
    });
  }
}