OpenAPI仕様の最新バージョンであるOpenAPI 3.0 (OAS 3.0)は昨年リリースされ、OASに標準化しようとするAPI開発者や組織の間ですでに採用が進んでいます。
OAS 3.0は、2015年に仕様がOpenAPI Initiativeに寄贈され、Swagger SpecificationからOpenAPI Specificationに名称変更されて以来、初のメジャーリリースとなりました。
昨年末、OpenAPI Initiativeのメンバーであるロン・ラトフスキー氏（OAI技術運営委員会のメンバーであり、SmartBearのSwagger開発エバンジェリスト）とオレ・レンスマー氏（OAI理事長）を招き、OAS 3.0の最新機能と強化点について議論する機会を得ました。
60分間のプレゼンテーションでは、スピーカーは仕様がどのように再構築されたか、最も期待している新機能は何か、そしてAPIチームがOAS 3.0への移行をどのように開始できるかについての見識を共有しました。
議論の完全なビデオはこちらで入手できます。しかし、プレゼンテーションからのクリップと重要なポイントをまとめた、より詳細な内訳も提供したかったのです。
この記事では、OASの最新バージョンにおける主要なアップデートのいくつかを紹介し、OAS 3.0への移行時に知っておくべきことを詳しく説明します。
再利用性を高めたシンプルな構造
OAS 3.0では、新しいよりシンプルな構造が導入されました。新しい構造は、OAS定義の記述とナビゲートを容易にすることを目的としており、OAS 2.0の既存のオブジェクトの一部を結合し、仕様の異なる部分に使用される命名を標準化し、OAS 3.0内で再利用性を拡張するための新しいオブジェクトも導入しています。
再利用可能なコンポーネントの数は4つから9つに増加し、本記事の後半で詳しく説明するリンクやコールバックなどの新機能が追加されました。
詳細はこちら
ドキュメントを読む: OpenAPI 3.0の構造
コンテンツネゴシエーションのサポート
OAS 3.0では、リクエストとレスポンスのボディの定義方法に多くの変更が導入されました。重要な変更点の1つは、ボディパラメータとフォームデータパラメータが削除され、requestBodyに置き換えられたことです。requestBodyは、JSON、XML、フォームデータ、プレーンテキストなどのさまざまなメディアタイプを消費し、異なるメディアタイプに異なるスキーマを使用できるという点で、より柔軟です。
その他の重要な変更点には、以下が含まれます。
- オペレーションは、フォームデータとJSONなどの他のメディアタイプの両方を消費できるようになりました。
- consumes配列は、メディアタイプをそのスキーマにマップするrequestBody.contentマップに置き換えられました。
- スキーマはメディアタイプによって異なります。
- フォームデータにオブジェクトを含めることができるようになり、オブジェクトと配列のシリアル化戦略を指定できるようになりました。
詳細はこちら
ドキュメントを読む: リクエストボディの記述
強化されたセキュリティ定義
OAS 3.0のセキュリティ定義の構造はOAS 2.0と一貫していますが、セキュリティフローの記述方法に影響を与えるいくつかの重要な変更点があります。最も注目すべき変更点の1つは、OAuth 2フローがOAuth 2仕様に合わせて名前が変更されたことです。`accessCode`は`authorizationCode`に、`application`は`clientCredentials`になりました。
追加の変更点には、以下が含まれます。
- `securityDefinitions`は`securitySchemes`に名前が変更され、`components`内に移動されました。
- `type: basic`は`type: http`および`scheme: basic`に置き換えられました。
- 新しい`type: http`は、Basic、BearerなどのすべてのHTTPセキュリティスキームの包括的なタイプであり、`scheme`キーワードはスキームタイプを示します。
- APIキーは`in: cookie`で送信できるようになりました。
- OpenID Connect Discoveryのサポートが追加されました（`type: openIdConnect`）。
- OAuth 2セキュリティスキームは、複数の`flows`を定義できるようになりました。
詳細はこちら
ドキュメントを読む: 認証と認可
更新されたパラメータ型
前述のとおり、OAS 3.0ではボディとフォームデータの2つのパラメータ型が削除されました。OAS 3.0では、新しいパラメータ型であるcookieも導入されました。これは、現在Cookieを使用しているAPIのドキュメント化のために要求された更新でした。
OpenAPI 3.0では、オペレーションパラメータでの配列とオブジェクトのサポートも含まれており、これらのパラメータをどのようにシリアル化するかを指定できます。シリアル化メソッドは、`style`および`explode`キーワードによって定義されます。
- `style`は、複数の値がどのように区切られるかを定義します。可能なスタイルは、パラメータの場所（パス、クエリ、ヘッダー、またはCookie）によって異なります。
- `explode` (true/false) は、配列とオブジェクトが各配列項目またはオブジェクトプロパティに対して個別のパラメータを生成するかどうかを指定します。
OpenAPIシリアル化ルールは、RFC 6570で定義されたURIテンプレートパターンのサブセットに基づいています。
詳細はこちら
ドキュメントを読む: パラメータの記述
改善された例
例は、APIをドキュメント化する上で重要な部分です。OAS 3.0には、仕様内で例を使用する方法の抜本的な見直しが含まれており、複数の例を記述する機能、API定義内で例を再利用する機能、および外部の例を参照する機能が含まれています。
例への変更により、例オブジェクトを使用する際の再利用性が向上しました。
詳細はこちら
ドキュメントを読む: 例の追加
OpenAPIリンクの紹介
リンクはOpenAPI 3.0の新機能の1つです。リンクは、APIの設計時にレスポンスとオペレーション間の関係を示すために使用される、APIの設計フェーズにまったく新しい概念を導入します。
リンクを使用すると、あるオペレーションによって返されるさまざまな値が、他のオペレーションの入力としてどのように使用できるかを記述できます。このように、リンクはオペレーション間の既知の関係とトラバーサルメカニズムを提供します。リンクの概念はハイパーメディアと比較されることが多いですが、OpenAPIリンクは実際のレスポンスにリンク情報が存在することを必要としません。
ドキュメントを読む: OpenAPIリンク
コールバック記述のサポート
OAS 3.0は、非同期APIまたはWebhooksを定義するために使用できるコールバックの記述をサポートしています。コールバックを使用すると、特定のイベントに応答してサービスが他のサービスに送信するリクエストを処理できます。これにより、APIがクライアントに提供するワークフローを改善できます。
コールバックは他のパス定義と同じ構造を使用し、Webhookが機能するためにクライアントが何を実装する必要があるかを記述できます。
ドキュメントを読む: コールバック
OAS 3.0の追加変更点
OpenAPI 3.0の主要な変更点に加えて、OAS 3.0への移行時に知っておくべき追加の更新がいくつかあります。
- OAS 3.0では、GitHub Flavored Markdown (GFM) からCommonMarkのサポートに移行しました。
anyOf、oneOf、notを含む拡張JSONスキーマのサポート。- 複数のサーバーとテンプレートサーバー定義の定義
- TRACEメソッドの新しいサポート
OAS 2.0からOAS 3.0への破壊的変更
OAS 3.0への変換を開始する準備ができている場合は、既存の定義を再構築するのに役立つツールがあります。SwaggerHubには、既存のスペックを3.0互換形式に変換し、簡単に開始できる組み込みコンバーターがあります。
プロセスを開始する際に焦点を当てる必要のあるいくつかの重要な領域もあります。
- 定義、パラメータ、レスポンス、およびセキュリティ定義はすべてコンポーネントの下に移動されます
- スキーム、ホスト、およびbasePathsはサーバーに置き換えられました
- パラメータを再構築する必要があります
- 型定義はスキーマの下に移動します
- ボディとフォームデータパラメータはrequestBodyに抽出されます
- レスポンスを再構築する必要があります
- producesメディアタイプはこのレベルに移動されます
- いくつかのセキュリティ定義の変更
- 'basic'が'http'に変更されました
- OAuth2フローは名前が変更され、わずかに異なる構造になりました
OAS 3.0の追加リソース
オープンソースのSwagger EditorとSwagger UI、またはSwaggerHubプラットフォームでOAS 3.0を使用してAPIの設計とドキュメント化を開始できます。また、開始に役立つお気に入りのOAS 3.0リソースもまとめました。