Question

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

我已经深入研究了aws文档，cdk示例，cdk参考，但是我可以找到具体的示例来帮助我理解如何做。

这是我的代码：

            if (err.domain == kCFStreamErrorDomainPOSIX) {
                DLog("POSIX err: %s", strerror(err.error));
            } else {
                DLog("domain: %d, value: %d", err.domain, err.error);
            }

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

Answer 1

据我所知，如果您使用CDK的默认部署选项（代表您创建阶段和部署），则不可能在阶段中附加文档版本集。

相反，解决方案是将RESTAPI的选项对象设置为deploy:false并手动定义阶段和部署。

stack.ts代码

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

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

    // create the API, need to not rely on CFN's automatic deployment because we need to 
    // make our own deployment to set the documentation we create
    const api = new apigateway.RestApi(this, 'books-api',{
      deploy: false
    });

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

    // // create documentation for GET method
    const docpart = 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
    });

    const doc = new CfnDocumentationVersion(this, 'docVersion1', {
      documentationVersion: 'version1',
      restApiId: api.restApiId,
      description: 'this is a test of documentation'
    });
    // not sure if this is necessary but it made sense to me
    doc.addDependsOn(docpart);

    const deployment = api.latestDeployment ? api.latestDeployment: new Deployment(this,'newDeployment',{
      api: api,
      description: 'new deployment, API Gateway did not make one'
    });
    // create stage of api with documentation version
    const stage = new Stage(this, 'books-api-stage1', {
      deployment:  deployment,
      documentationVersion: doc.documentationVersion,
      stageName: 'somethingOtherThanProd'
    });
  }
}

输出：

在此处为此选项创建了feature request。

Answer 2

我已经使用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'
    });
  }
}

Answer 3

我遇到了同样的问题。 CfnDocumentationVersion 调用必须在您创建所有 CfnDocumentationPart 之后发生。以您的代码为例，它应该如下所示：

class APISiteDocs extends Stack {

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

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

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

  }
}

如何使用AWS CDK记录Rest API

3 个答案: