AWS CDKで作ったAPI Gateway + LambdaからOpenAPIドキュメントを生成してみた

Qiita Advent Calendar 2023 「AWS CDK」 3日目の記事です。
https://qiita.com/advent-calendar/2023/aws-cdk

はじめに

普段の開発でAPIの仕様は基本的にOpenAPI(旧Swagger)で書いているのですが、個人的に仕様書とか設計書を手動で書くのは面倒くさく感じてしまう人種であります。ですので、API仕様書なんてものはコードから自動生成したいものです。
主要なAPIフレームワークを活用していれば比較的容易に実現できます。PythonのFastAPI、Node.jsのNestJSやFastifyであれば標準(またはそれに準ずる)機能でOpenAPIドキュメントを自動生成出来ます。Expressでもexpress-oas-generatorといったプラグインの活用で実現可能です。
ですが、サーバレスが主流になりつつある昨今では、API Gateway + Lambdaからでも自動生成したいと思いました。

前置きが長くなりましたが、API Gateway + LambdaのAPIからOpenAPIドキュメントを自動生成します。

作成済みのApi Gatewayから、AWS CLIでOpenAPIドキュメントを生成する

ググったら出てきた。普通に出来るみたいです。
https://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/api-gateway-export-api.html

試してみた

Api Gatewayは、V1(RestAPI)とV2(HttpAPI)があり、何故かCLIのコマンドが全く違うので両方試してみます。jsonよりyaml派なのでyamlで出力します。

• V1(RestAPI)の場合

aws apigateway get-export --parameters extensions='integrations' --rest-api-id {api-id} --stage-name prod --export-type oas30 --accepts "application/yaml" openapi.yaml  --profile {aws-profile}

• V2(HttpAPI)の場合

aws apigatewayv2 export-api --api-id {api-id} --output-type YAML --specification OAS30 openapi-v2.yaml --profile {aws-profile}

出力することが出来ました。
試すときは{api-id}や{aws-profile}のパラメータは、自分の環境にあわせて変更してください。

以上です。

CDKでAPI Gateway(V2) + Lambdaをデプロイした後、OpenAPIを出力してみる

これで終わりだと記事が短すぎるので、CDKでAPI GatewayとLambdaをデプロイして、そのまま自動でOpenAPIを出力するようにしてみます。
普段はAPI GatewayをRestAPIで作ることが多いので、今回は個人的に馴染みの薄いHttpAPIつまりAPI Gateway V2で試してみます。

CDKでAPI Gateway(V2) + LambdaをデプロイするStackを書く

こんな感じで出来ました。
https://github.com/k-ibaraki/api-gw-lambda-openapi/blob/main/lib/ibaraki-cdk-sample-api-v2-stack.ts
Lambdaのコードは貼りませんが、GitHubのレポジトリには置いてあります。

CDKでDeployして、api-idを出力する

実際にデプロイしてみます。

cdk deploy IbarakiCdkSampleApiV2Stack -O output.json --profile {aws_profile}

✨  Synthesis time: 2.42s

(省略)

Outputs:
IbarakiCdkSampleApiV2Stack.ApiId = **********
Stack ARN:
arn:aws:cloudformation:ap-northeast-1:************:stack/IbarakiCdkSampleApiV2Stack/********-****-****-****-************

-Oオプションにより、出力結果がファイルに保存されます

output.json

{
  "IbarakiCdkSampleApiV2Stack": {
    "ApiId": "**********"
  }
}

CDKの補足

aws-cdk-lib/aws-apigatewayv2が標準で用意されているのですが中身がスカスカで使い物になりませんでした。なので、正式リリース前の@aws-cdk/aws-apigatewayv2-alphaと@aws-cdk/aws-apigatewayv2-integrations-alphaを使っています。

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-apigatewayv2-alpha-readme.html
https://docs.aws.amazon.com/cdk/api/v2/docs/aws-apigatewayv2-integrations-alpha-readme.html

正式版じゃないものを使うのはちょっと怖いので本番プロジェクトでの使用は気をつけましょう。(2023年時点では、まだApi Gatewayはv1を使ったほうが無難なのかもしれません。)

CDKをDeployして、OpenAPI出力するスクリプトを書く

こんな感じになりました。
https://github.com/k-ibaraki/api-gw-lambda-openapi/blob/main/scripts/deploy-v2.sh

実行するときはこんな感じです。

sh scripts/deploy-v2.sh -s IbarakiCdkSampleApiV2Stack -p {aws-profile}

package.jsonにも書いておく

package.jsonに実行コマンドを書いて、npm runから起動できるようにします。
https://github.com/k-ibaraki/api-gw-lambda-openapi/blob/main/package.json#L13

作ったスクリプトとCDKで、DeployからOpenAPIのドキュメント生成まで一発でやる

npm run deploy-v2 -- -p {aws-profile}

結果

デプロイ後にOpenAPIのyamlファイルが出力されました。

今度こそ、以上です。
Responseの定義とかまともに出来てないので、実用性がどこまであるか微妙ですが、deploy後すぐにOpenAPIからAPIを試せるのでそこそこ便利です。

この記事のソースコード

GitHubに置きました。
https://github.com/k-ibaraki/api-gw-lambda-openapi

• v1(RestAPI)版も作ったので置いてあります。
• openAPIのexportをAWS SDKを使で実行するコードも書いてみたんですけど、cliのほうが楽だったのでボツにしました。せっかく書いたのでGitHubにコードは置いてあります。