CDK部署后如何自动生成导出ApiGateway的Swagger JSON文件

1 CfnDocumentationPart报错修复 #

错误触发规则：API Gateway的RESOURCE类型文档部位仅支持path参数，不允许携带method、statusCode、name字段。你需要配置405响应说明，应将location.type修改为RESPONSE类型，正确代码如下：

import * as apigateway from 'aws-cdk-lib/aws-apigateway';

// 你的RestApi实例定义
const api = new apigateway.RestApi(this, 'mycomRestApi', {
  deployOptions: {
    stageName: 'prod'
  }
});

new apigateway.CfnDocumentationPart(this, 'siteDocs', {
  restApiId: api.restApiId,
  location: {
    type: 'RESPONSE', // 替换为RESPONSE类型
    method: '*',
    path: '/',
    statusCode: '405'
  },
  // 建议用JSON.stringify避免模板字符串格式错误
  properties: JSON.stringify({
    status: "error",
    code: 405,
    message: "Method Not Allowed"
  })
});

如果仅需要给指定路径的资源加整体说明、不需要绑定方法和状态码，使用RESOURCE类型时去掉method、statusCode字段即可。

2 部署后自动导出Swagger JSON实现方案 #

推荐用CDK原生的部署钩子实现，无需额外自定义资源，配置步骤如下：

步骤1：在CDK栈中添加必要参数输出 #

// 输出API ID和部署阶段名，供后续命令调用
new cdk.CfnOutput(this, 'RestApiId', {
  value: api.restApiId
});
new cdk.CfnOutput(this, 'RestApiStage', {
  value: api.deploymentStage.stageName
});

步骤2：配置CDK部署后钩子 #

修改项目根目录的cdk.json，新增postdeploy钩子配置：

{
  "app": "npx ts-node --prefer-ts-exts bin/你的项目入口文件名.ts",
  // 原有watch、context配置保留不变
  "hooks": {
    "postdeploy": [
      "aws apigateway get-export --parameters extension='integrations' --rest-api-id $(aws cloudformation describe-stacks --stack-name 你的CDK栈名 --query \"Stacks[0].Outputs[?OutputKey=='RestApiId'].OutputValue\" --output text) --export-type swagger --accepts application/json --stage-name $(aws cloudformation describe-stacks --stack-name 你的CDK栈名 --query \"Stacks[0].Outputs[?OutputKey=='RestApiStage'].OutputValue\" --output text) swagger_new.json"
    ]
  }
}

配置完成后，每次执行cdk deploy完成后会自动执行导出命令，将Swagger定义输出到项目根目录的swagger_new.json文件中。

注意：执行环境需要提前配置好对应AWS账号的访问凭证，且已安装AWS CLI工具。

内容的提问来源于stack exchange，提问作者James Black