AWSにおける公開APIのリノベーション術/cariot-jaws-ug-lunch-36

2026年6月23日に開催された『JAWS-UG東京 ランチタイムLT会 #36』の発表資料です。

https://jawsug.connpass.com/event/395046/

Transcript

1. AWSにおける公開APIのリノベーション術 株式会社キャリオット 遠藤 匠 2026/06/23 JAWS-UG東京 ランチタイムLT会 #36
2. 2 自己紹介 遠藤 匠 株式会社キャリオット プロダクト開発部 AWSを使った B2Bプロダクトを開発してます
3. 3 AWS Cloud 現行APIの管理 Amazon API Gateway Amazon S3 YAML OAS 2.0 (Swagger 2.0) オーソドックスなREST API put-rest-api create-deployment GitHub Actions s3 cp API Users
4. 4 内側（コードメンテナンス） • Swagger (OpenAPI) 形式 • 15,000行overの単一YAML • CORS関連の設定も自前 課題 • 修正コストが高い （人にとってもAIエージェントにとっても）
5. 5 外側（開発者向けドキュメントとしてのユーザビリティ） • Swagger UI • メソッドの簡単な説明のみで、 概要、認証・認可、レート制限など、 使用上の留意点については ドキュメント外 課題 • 利用者にとっての情報が不足
6. 6 リノベーション術 Swagger UI 単一Swagger (OpenAPI) ファイル コードメンテナンス 開発者ドキュメント TypeSpec API Gateway デベロッパーポータル Docusaurus
7. 7 TypeSpec • API定義のための言語（DSL） • Microsoft製 • TypeScriptライクな構文 import "@typespec/http"; using Http; model Store { name: string; address: Address; } model Address { street: string; city: string; } @route("/stores") interface Stores { list(@query filter: string): Store[]; read(@path id: Store): Store; } ※ 似たような？ものに AWS PDK (Project Development Kit)というのがあるけど、 あんまり動いてなさそう… https://aws.github.io/aws-pdk/developer_guides/type-safe-api/index.html
8. 8 既存YAMLのTypeSpec化 OpenAPI YAML TypeSpec パス @route + @get パラメータ @query, @path, @header デコレータ スキーマ model リクエストボディ @bodyを明示するか、@path/@query以外の引数が暗黙的にbody扱いになる レスポンス 戻り値の型がそのまま200レスポンスに。 バリデーション @minLength, @minValue デコレータ等 additionalProperties Record<T> • 基本的には変換表に沿って機械的に変換可能 • 変換ツール (tsp-openapi3)も提供されている
9. 9 TypeSpec × API Gateway • x-amazon-apigateway-* ではじまるベンダー拡張 ◦ 自作デコレータ ◦ @extension（標準搭載されている拡張記法） • 一部の変換は力技で対応（下表） 要対応箇所 対策 愚直に書いていたCORSプリフライ トのOPTIONSが表現不可 実メソッドの定義から自動生成して、post-emitで注入 /api/foo/{proxy+}のANYが表現不 可 原文をそのままpost-emitで注入
10. 10 API Gatewayデベロッパーポータル API Gatewayネイティブな開発者向け ポータルサイト提供機能 • 2025年11月リリース • 以前からawslabsでOSSテンプレートと して提供されていたのとは別物 ◦ https://github.com/awslabs/aws-api-gat eway-developer-portal • フルマネージドな別サービスとして 生まれ変わった https://aws.amazon.com/jp/blogs/compute/ improve-api-discoverability-with-the-new-amazon-api-gateway-portal/
11. 11 API Gatewayデベロッパーポータル • 機能 ◦ ビジネスロジックに合わせた単位でAPIをパッケージ化して公開可 ◦ 異なるアカウントにあるAPIを一箇所に集約して公開 ◦ セキュリティやアクセス制御 ◦ インタラクティブなテスト機能（Try it） • 月額147ドル + ポータルごと14.70ドル ◦ やや高め…？ ◦ コストに見合うかどうかはケースバイケース（今回は見送り…）
12. 12 代替アプローチ: Docusaurus • OSS静的サイトジェネレータ ◦ React / Markdown / MDX (Markdown + JSX) • Meta製 • ドキュメントの解説ページとAPIリファレンスを1サイトに統合 • バージョニング、国際化、検索、ダークモードなどに対応
13. 13 TypeSpec × Docusaurus TypeSpec (*.tsp) OpenAPI 3.0 tsp compile 一部APIを除去 MDXファイル docusaurus gen-api-docs build/*.html docusaurus build S3 + Cloudfront 仕様定義 サイト作成 公開
14. 14 成果ドキュメント
15. 15 まとめ：APIのリノベーション 単一の巨大なYAMLファイルを TypeSpecで分割統治された コード化へ（コード量も40%減） TypeSpecをSingle Source of Truthとして、Docusaurus + S3 + Cloudfrontでホスティング 内側（定義ファイルのメンテナンス） 外側（利用者向けポータル） 開発者、利用者、AIの三方良しなAPI定義の運用
16. ご清聴ありがとうございました https://www.cariot.jp/ We're hiring!