OpenAPI Specification 3.0での変更点について
最近の記事
Swaggerをベースとして策定が進んでいるOpenAPI Specification 3.0ですが、その内容がブログ記事になっていました。
大きく分けて6つの点が課題として掲げられています。
1. 構造の改善
Swaggerでは粒度が異なる状態で混在していた構造について、大きく変更されています。以下は TDC: Structural Improvements: explaining the 3.0 spec, part 2 | Open API Initiative にて紹介されていた画像です。
via TDC: Structural Improvements: explaining the 3.0 spec, part 2 | Open API Initiative
definitions/parameters/responses/produces/consumesといったオブジェクトがなくなり、すべてcomponentsに統合または廃止されるようです。結果として構造はとてもすっきりしています。
2. バージョン定義の変更
これまでは 2.0 という書き方でしたが、今後は 3.0.0 のようにパッチバージョンを含むようになります。バージョン番号は セマンティック バージョニング 2.0.0 - Semantic Versioning に則った形で管理されます。
3. Components
上記画像でもありますが、Componentsというオブジェクトが追加されます。2.0では幾つかのプロパティがグローバルに適用されていたり、スコープに矛盾が見られました。そこでComponentsでは再利用されるメタデータだけをまとめて管理するようになります。
4. マルチホスト
Swaggerではhostは一つしか存在できません。3.0ではhostsとなり、複数ホストを管理できるようになります。それぞれベースパスやスキーマも格納されるようになります。さらにpathの中でhostを定義して上書きもできるとのことです。
5. 他の記述オプション
これまではオペレーションレベルで書かれていたのが、今後はリソース指向で作られるようになります。リソース指向では GET a foo、POST a foo、DELETE a fooといった具合にリソース（foo）に対して何かするといった具合に読めるものです。パスの説明では短い説明文と長い説明文を使えるようになります。
6. レスポンス例の拡張
これまではJSONまたはYAMLでのみ記述できましたが、これが大幅に拡張されます。JSONを使って任意のフォーマットで記述できるとのことで、 $ref プロパティを使って外部ファイルを参照するようにもできます。
基本的には構造が変わるとのことで、これに合わせてSwagger用のツールも変更が求められるでしょう。構造的には分かりづらい部分も多かったので、3.0によって全体の見通しが良くなったように感じられます。リリースはまだですが、OAI/OpenAPI-Specification: The OpenAPI Specification Repositoryにてディスカッション内容は見られるようになっています。
via TDC: Structural Improvements: explaining the 3.0 spec, part 2 | Open API Initiative