Documentation 如何使用aws cdk记录rest api

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

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

这是我的密码：

const-app=new-app（）；
const-api=new-APIStack（app，'APIStack'，{env}）；//基本api网关
//API资源
const resourceProps:APIResourceProps={
网关：api.gateway，
}
//带有一些HTTP方法的虚拟端点
const siteResource=新的APISiteStack（应用程序“APISiteStack”{
环境，
…资源道具
});
const siteResourceDocs=新的APISiteDocs（应用程序“APISiteDocs”{
环境，
…资源道具，
});
//APISiteDocs的定义如下：
类APISiteDocs扩展堆栈{
构造函数（作用域：Construct，id:string，props:APIResourceProps）{
超级（范围、id、道具）；
新的CFN文档版本（此“apiDocsVersion”{
restApiId:props.gateway.restApiId，
documentationVersion:config.app.name（`API-${config.gateway.API.version}`），
描述：“备用It API文档”，
});
新的CfnDocumentationPart（此“siteDocs”{
restApiId:props.gateway.restApiId，
地点：{
类型：“资源”，
方法：'*'，
路径：apistestack.apiBasePath，
状态代码：“405”，
},
特性：`
{
“状态”：“错误”，
“代码”：405，
“消息”：“不允许使用方法”
}
`,
});
}
}

---

非常感谢您提供的任何帮助/提示。

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

相反，解决方案是将RESTAPI的option对象设置为

deploy:false

，并手动定义stage和deployment

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'
    });
  }
}

输出：

---

在此处为此选项创建了一个

我已经用CDK 1.31进行了测试，可以使用CDK的默认部署选项，也可以向后台添加文档版本。我使用rest api定义中的

deployOptions.documentVersion

设置api文档的版本标识符：

从'@aws cdk/core'导入*作为cdk；
从“@aws cdk/aws apigateway”导入*作为apigateway；
从“@aws cdk/aws apigateway”导入{CfnDocumentationPart，CfnDocumentationVersion}；
导出类CdkSftpStack扩展了cdk.Stack{
构造函数（作用域：cdk.Construct，id:string，props？：cdk.StackProps）{
超级（范围、id、道具）；
const documentVersion=“v1”；
//创建API
const api=new apigateway.RestApi（这是“books api”{
部署：对，
部署选项：{
文档版本：文档版本
}
});
//在/books资源上创建GET方法
const books=api.root.addResource（'books'）；
books.addMethod（'GET'）；
////为GET方法创建文档
新的CFN文件部分（本“文件部分1”）{
地点：{
类型：'方法'，
方法：“GET”，
路径：books.path
},
属性：JSON.stringify({
“状态”：“成功”，
“代码”：200，
“消息”：“获取方法已成功”
}),
restApiId:api.restApiId
});
新的CFN文档版本（此“docVersion1”{
文档版本：文档版本，
restApiId:api.restApiId，
描述：“这是对文档的测试”
});
}
}

---

我也有同样的问题。创建所有

CfnDocumentationPart

后，必须调用

CfnDocumentationVersion

。以您的代码为例，它应该如下所示：

类APISiteDocs扩展堆栈{
构造函数（作用域：Construct，id:string，props:APIResourceProps）{
超级（范围、id、道具）；
新的CfnDocumentationPart（此“siteDocs”{
restApiId:props.gateway.restApiId，
地点：{
类型：“资源”，
方法：'*'，
路径：apistestack.apiBasePath，
状态代码：“405”，
},
属性：JSON.stringify({
“状态”：“错误”，
“代码”：405，
“消息”：“不允许使用方法”
}),
});
新的CFN文档版本（此“apiDocsVersion”{
restApiId:props.gateway.restApiId，
documentationVersion:config.app.name（`API-${config.gateway.API.version}`），
描述：“备用It API文档”，
});
}
}

我还没有用过，但我一直推荐TSDoc@citadelgrad谢谢，我更喜欢CDK方式而不是TSDocThanks方式。我要试试，让你知道