OpenAPI は、HTTP APIの仕様を標準的な形式で記述するための仕様です。
エンドポイント、HTTPメソッド、リクエスト、レスポンス、認証方式、エラー形式などをJSONやYAMLで書き、ドキュメント表示、テスト、モック、コード生成などに活用できます。
まず押さえたいポイント
- API仕様書を機械にも人にも読める形で書ける
openapi.yamlやopenapi.jsonとして管理されることが多い- REST API やHTTP APIの共有に使われやすい
- Swagger UIなどのツールで見やすいドキュメントにできる
- 実装と仕様書がずれると価値が落ちる
OpenAPIは、単なる説明文ではありません。
仕様書として書いておくことで、フロントエンド、バックエンド、QA、外部連携先が 何を送ればよいか 何が返るか を同じ形で確認しやすくなります。
どんな場面で使うか
OpenAPIは、APIを複数人で作る場面で特に役立ちます。
バックエンドが実装したAPIをフロントエンドが使う、外部会社へ連携仕様を渡す、QAがテスト観点を作る、SDKやモックサーバーを生成する、といった場面です。
仕様書がないと、実装コード、チャット、口頭説明、古い設計書を突き合わせる必要があります。
OpenAPIとしてまとまっていると、APIの入口、入力、出力、エラー、認証方式を同じ場所で確認できます。
Swaggerとの違い
実務では Swagger という名前もよく出ます。
現在は、OpenAPIが仕様の名前、SwaggerはOpenAPIを扱うツール群や旧称として使われることが多いです。
たとえば、Swagger UIで表示しているAPIドキュメントの中身はOpenAPI形式の仕様書、という関係で見ると分かりやすいです。
注意点
OpenAPIを書けばAPI設計が自動的によくなるわけではありません。
実装が変わったのに仕様書が更新されない、成功レスポンスだけ書いてエラーがない、認証や権限条件が説明されていない、サンプルと実際のレスポンスが違う、という状態では利用側が混乱します。
そのため、API変更時はOpenAPIもレビュー対象にし、できればテストやCIで実装と仕様のズレを検出できるようにしておくと安全です。
OpenAPIとSwaggerの違い、API仕様書をチームで共有するときの基本は、OpenAPI / Swaggerとは？API仕様書をチームで共有する基本を整理 で詳しく整理しています。