API仕様書(Swagger等)
REST/GraphQL などのエンドポイント情報を定義し、クライアントとサーバの契約を明文化します。
目的
フィールドやエラーレスポンスを正確に共有し、並行開発や自動テストを容易にします。
主な内容
- エンドポイントURI、HTTPメソッド、認証条件
- リクエスト/レスポンスのスキーマ、例
- ステータスコード、エラーコード、再試行ルール
活用ポイント
- OpenAPIなど機械可読な形式で管理し、ドキュメント生成を自動化
- バージョンポリシーと互換性方針を明記
- モックサーバやSDK生成と連動させ、利用者の導入コストを下げる