BASEプロダクトチームブログ

ネットショップ作成サービス「BASE ( https://thebase.in )」、ショッピングアプリ「BASE ( https://thebase.in/sp )」のプロダクトチームによるブログです。

AWS API Gatewayのdocumentation partを利用してAPIの仕様書をいい感じにする

BASEアドベントカレンダー2021 11日目の記事です。

f:id:HifiroleLorum:20211210172421p:plain
BASEアドベントカレンダー2021

DataStrategyチームの齋藤(@pigooosuke)です。
DataStrategyチームでは機械学習のモデルや集計結果をAPI経由で配信することが多く、社内の他チームと連携する際にも、どういうリクエストパラメータが存在し、どういうレスポンスが期待されるのかを共有しています。
弊チームでは、AWSのAPI Gatewayを利用しているので、API Gatewayの機能として提供されているドキュメントパーツを利用して共通フォーマットのAPI仕様書を管理しています。
markdown記法によるドキュメント管理に比べ、各APIのリクエストパラメーターやレスポンスモデルの視認性の改善や更新漏れが減るようになりました。

今回は、どのようにAPI仕様書を管理しているのかを紹介したいと思います。

*現在利用しているRedocのデモ画像

f:id:HifiroleLorum:20211210172840p:plain
Redocのデモ画像

API Gateway ドキュメントパーツ

API Gatewayでは各APIリソースに紐づくレスポンスモデル、クエリパラメータ、リクエストヘッダーなどに対して、ドキュメントを設定することができます。かつ、設定されたドキュメントを全て結合して、OpenAPI 3もしくはSwagger形式のjson/yamlを出力することが出来ます。

AWS デベロッパーガイド: API Gateway での API ドキュメントの表現

例えば、 /ysaito/recommendという「おすすめコンテンツを配信するAPI(GET method)」を提供していると仮定して、 このAPIでは、パラメータとしてユーザーIDと最大取得件数を指定できるとします。 その場合、

  • /ysaito/recommendに対するドキュメント
  • /ysaito/recommendに含まれるクエリパラメータユーザーID(user_id)に対するドキュメント
  • /ysaito/recommendに含まれるクエリパラメータ最大取得件数(max_size)に対するドキュメント

をそれぞれ個別に管理することが出来ます。 今回のケースでは、コンソール画面上では以下のように登録されます。

f:id:HifiroleLorum:20211210172941p:plain

合わせて、APIレスポンスに関しても、 API Gatewayのモデル管理でモデル登録&APIに紐付けしておくことで出力ファイルにレスポンスモデルを含めることが可能です。もちろん200以外のステータスコードの登録も可能です。

f:id:HifiroleLorum:20211210173021p:plain

またこのドキュメントのリリースバージョンは、API Gateway本体のデプロイと同様にバージョン管理されているので、必要に応じて、過去のリリースバージョンにロールバックなども容易に可能になっています。

概略

全体のフローとして以下の図の通りです。

f:id:HifiroleLorum:20211210173055p:plain

  1. API GatewayにAPI定義をTerraformを利用して登録する
  2. ビルド用のrepositoryがAPI GatewayからOpenAPI/swagger仕様のAPI定義ファイルを取得する
  3. RedocというOpenAPI/swaggerファイルをHTMLファイルに変換するツールでビルドする
  4. S3にアップロードし、ドキュメント公開用サーバー上で公開する

処理詳細

API GatewayにAPI定義をTerraformを利用して登録する

Document PartsはTerraformで管理することができるため、APIを作成する場合に合わせて登録するようにしています。 Terraform: Resource: aws_api_gateway_documentation_part

ビルド用のrepositoryがAPI GatewayからOpenAPI/swagger仕様のAPI定義ファイルを取得する

ビルド用のRepositoryのGitHub Actionsでは、AWS CLIにてAPI Gatewayからのドキュメント取得を以下のコマンドで取得しています。

aws apigateway get-export --parameters extensions='apigateway' --rest-api-id `<API ID>` --stage-name prod --export-type oas30 --accepts application/yaml `<出力先path>`

RedocというOpenAPI/swaggerファイルをHTMLファイルに変換するツールでビルドする

OpenAPI/swaggerファイルをHTML変換するツールはいくつか公開されているのですが、 視認性の観点でRedocを採用しています。

おわりに

今回は、API仕様書の管理について紹介してみました。 ドキュメントの管理は、「昔の情報から更新されてない」「誰が管理するの？」といった長年の課題ではありますが、 API Gatewayの開発と連動して、自動でドキュメント発行できる仕組みを運用することで負荷軽減に繋がりました。

明日のアドベントカレンダーはフロントエンドエンジニアのがっちゃん（ @gatchan0807 ）の記事です。お楽しみに！