SwaggerがOpenAPI 3.1のサポートを開始
Swaggerオープンソースエコシステム全体でOpenAPI 3.1の一般サポートを発表できることを嬉しく思います。
要するに;
🎉SwaggerはOpenAPI 3.1の編集およびレンダリングをサポートするようになりました。
SwaggerはJSON Schema 2020-12のレンダリングをサポートしています。
Swagger UI、Swagger Client、Swagger Editor (Next)、Swagger Parser、Swagger Core、ApiDOM全体でOpenAPI 3.1のサポートが追加されました。
以前の更新と、リッチな編集および検証機能が追加された新しい製品の発表に続き、Swagger UI内でOpenAPI 3.1ドキュメントのレンダリングがサポートされ、JSON Schema Specificationの最新バージョン（Draft 2020-12）の幅広いサポートも提供されるようになりました。
このマイルストーンは、新しいSwagger EditorがAsyncAPI（バージョン2.*）に対してすぐに使用できるサポートを提供することと同時に達成されました。これにより、SwaggerはOpenAPIとAsyncAPIのすべてのバージョンで作業する開発チームに豊かな体験をもたらします。
OpenAPI 3.1とは？
OpenAPI 3.1は（執筆時点で）OpenAPI Specification（OAS）の最新バージョンです。OpenAPI Specificationは、HTTP APIの標準的で言語に依存しないインターフェース記述を定義します。これにより、人間もコンピュータも、ソースコードへのアクセス、追加ドキュメント、ネットワークトラフィックの検査を必要とせずに、サービスの機能（API）を理解できるようになります。
OpenAPI 3.1では、OAS技術運営委員会（TSC）は、コミュニティでの議論を経て、セマンティックバージョニングに従わないことを決定しました。これにより、JSON Schema 2020-12との整合性を図り、OpenAPI 3.0からの学びに対処するために、マイナーバージョンアップで特定の破壊的変更を許容しています。変更点はリリースノートに記載されています。
OpenAPI 3.1には多くの改善が含まれています。私たちにとっての注目すべき追加/変更点は次のとおりです。
Schema ObjectはJSON Schema Draft 2020-12に完全に準拠し、プリミティブ型もJSON Schema Draft 2020-12に基づいています。WebhooksがOpenAPI Objectのトップレベルフィールドとして導入され、APIの一部として利用可能な帯域外登録済みウェブフックの記述が可能になりました。Components ObjectでpathItemsの定義が可能になり、OpenAPIドキュメント内で再利用可能なPath Item Objectの利用が促進されました。Info Objectは、既存のdescriptionフィールドに加えてsummaryフィールドをサポートするようになりました。- License ObjectにSPDXライセンスコードの新しい識別子フィールドが追加されました。
- 有効なOpenAPIドキュメントの構成も変更されました。仕様では、トップレベルに
paths、components、またはwebhooksのいずれかが少なくとも1つ存在することが要求されるようになりました。以前の仕様バージョンではpathsが必須でした。現在では、有効なOpenAPIドキュメントはウェブフックのみ、または再利用可能なコンポーネントのみを記述することもできます。
変更点の詳細については、Mike Ralphson（OAS TSCメンバー）によるこの記事をご覧ください。
SwaggerにおけるOpenAPIサポート
以下は、OpenAPI 3.0および3.1の現在のサポートレベルの概要です。フィールドレベルでの詳細な内訳については、近日中に改めてお知らせします。
|
OAS
|
ApiDOM
|
Swagger Editor (next)
|
Swagger Core
|
Swagger Parser
|
Swagger UI
|
Swagger Client
|
|
OpenAPI Object
|
|
|
|
|
|
|
|
Info Object
|
|
|
|
|
|
|
|
Contact Object
|
|
|
|
|
|
|
|
License Object
|
|
|
|
|
|
|
|
Server Object
|
|
|
|
|
|
|
|
Server Variable Object
|
|
|
|
|
|
|
|
Component Object
|
|
|
|
|
|
|
|
Paths Object
|
|
|
|
|
|
|
|
Path Item Object
|
|
|
|
|
|
|
|
Operation Object
|
|
|
|
|
|
|
|
External Documentation Object
|
|
|
|
|
|
|
|
Parameter Object
|
|
|
|
|
|
(一部制限あり)
|
|
Request Body Object
|
|
|
|
|
|
|
|
Media Type Object
|
|
|
|
|
|
|
|
Encoding Object
|
|
|
|
|
|
(一部制限あり)
|
|
Responses Object
|
|
|
|
|
|
|
|
Response Object
|
|
|
|
|
|
|
|
Callback Object
|
|
|
|
|
|
|
|
Example Object
|
|
|
|
|
|
|
|
Link Object
|
|
|
|
|
|
|
|
Header Object
|
|
|
|
|
|
|
|
Tag Object
|
|
|
|
|
|
|
|
Reference Object
|
|
|
|
|
|
|
|
Schema Object
|
(一部制限あり)
|
(一部制限あり)
|
(一部制限あり)
|
(一部制限あり)
|
(一部制限あり)
|
(一部制限あり)
|
|
Discriminator Object
|
|
|
|
|
|
|
|
XML Object
|
|
|
|
|
|
|
|
Security Scheme Object
|
|
|
|
|
|
|
|
OAuth Flows Object
|
|
|
|
|
|
|
|
OAuth Flow Object
|
|
|
|
|
|
|
|
Security Requirement Object
|
|
|
|
|
|
|
|
Specification Extensions
|
|
|
|
|
|
|
次なるステップ
次の焦点は、OpenAPI 3.1サポートに見られるギャップを埋めることです。また、幅広いコミュニティと協力して、OpenAPI 3.1向けの最新Swagger機能の定着と採用を確実にする予定です。
私たちは、幅広いAPI仕様と言語にわたるAPIコミュニティをサポートすることに尽力しています。そのため、Swaggerのロードマップを公開し、最新のイノベーションに関するアップデートを提供する予定です。プロジェクト間の仕様サポートについて透明性を確保するため、その参照情報を近日中に公開します。
Swaggerのオープンソースイニシアチブへのご参加を心よりお待ちしております。ぜひ貢献ガイドをご確認いただき、変化をもたらすことにお役立てください。