OpenAPI 3.0およびOpenAPI 3.1に対するSwaggerのサポート

Swagger Editorの新しいバージョンが最近リリースされたことを受け、OpenAPI 3.0での編集およびレンダリング体験を幅広くサポートしていることを喜んでお知らせします。 

OpenAPI 3.1のサポートに向けて、Swaggerエコシステム全体で活発な活動が続いています。OpenAPI 3.1はOpenAPI Specificationの最新バージョンです。  

現在、新しいエディターは、OpenAPI 3.0および3.1における言語固有のドキュメント、より優れたオートコンプリート、バリデーション、構文ハイライト、「移動」参照、「シンボルの検索」などの機能を網羅する豊富な編集体験をサポートしています。OpenAPI 3.1のレンダリングは、Swagger UIの機能強化の一環として間もなく提供される予定です。 

今回の最新機能リリースは、新しいエディターがAsyncAPI（バージョン2.*）をすぐにサポートすることに伴い、Webブラウザ内でOpenAPIとAsyncAPIの両方で豊富な編集体験を提供します。 

さらに、Swagger OSSスイートのプロジェクト全体におけるOpenAPI Specification (OAS) 3.1のサポートに関する簡単な最新情報です。 

Swagger Core 2.2.0のリリースでは、表現、(非)シリアル化、アノテーションとコードファーストの仕様解決の部分的なサポートに関して、OpenAPI 3.1 / JSON Schema 2020/12のサポートが導入されました。OAS 3.1のサポートは、現在OAS 3.0のサポートを提供しているのと同じコードラインに追加されました。  

Swagger CoreおよびParserのマスターブランチは、以下のアーティファクトを生成します。 

• io.swagger.core.v3:swagger-core:2.2.x  
• io.swagger.parser.v3:swagger-parser:2.1.x  

本稿執筆時点では、コードファーストのOAS 3.1仕様解決とアノテーションのサポートは進行中であり、3.1は現在、生成された3.0からの変換によって提供されています。表現の観点から見ると、swagger-modelsはOpenAPI 3.x定義のPOJO表現を提供します。 

Swagger Parserは、(当然ながら) OpenAPI仕様をSwagger Coreのswagger-modelsモジュールによって提供されるOpenAPIインスタンスにパースします。バージョン2.1.0以降、OAS 3.0と同じAPIを使用してOpenAPI 3.1仕様のパースとバリデーションをサポートしています。  

OpenAPIフィールドの値をチェックすることでバージョンを検出します。 

    SwaggerParseResult result = new 
    OpenAPIParser().readLocation("./path/to/openapi31.yaml", null, null);  
    OpenAPI = result.getOpenAPI();
    

返されるOpenAPIインスタンスは、Swagger Coreの非シリアル化によって取得されるものと類似しています。 

Swagger Parserバージョン2.1.0以降、バリデーションはOAS 3.1仕様ルールもサポートしており、OpenAPIフィールドによってバージョン3.1定義が検出されたときに適用されます。バリデーションエラーは、3.0と同様に`SwaggerParseResult`内に提供されます。 

OpenAPI 3.1仕様を処理する場合、Swagger Parserは3.0ドキュメントに使用されるものとは異なるロジックで解決（`options.setResolve(true)`）します。このようなロジックは、より一貫性があり、保守しやすいように設計されています。 

Swagger CoreおよびSwagger ParserのOpenAPI 3.1サポートの詳細については、GitHubのwikiを参照してください。 

OpenAPI 3.1のレンダリングは、Swagger UIの機能強化の一環として間もなく提供される予定です。要するに、Swagger UI内でのOpenAPI 3.1定義/ドキュメントの処理およびレンダリング機能は、ApiDOMとSwagger Clientの統合によって有効になります。 

2023年第1四半期にはこれが完了し、レンダリング機能もSwagger Editorツールに搭載される予定です。 

OpenAPI 3.0および3.1サポートの概要 

以下は、OAS 3.0および3.1の現在のサポートレベルの概要です。フィールドレベルでのより詳細な内訳については、近日中に追ってご連絡します。 

次のステップ 

私たちは、API仕様や言語のあらゆる分野でAPIコミュニティをサポートすることをお約束します。  

その一環として、Swaggerのロードマップを公開し、最新のイノベーションについて最新情報を提供する予定です。さらに、プロジェクト全体での仕様サポートについて透明性を確保したいと考えており、その参照情報は近日中に公開します。 

Swaggerにおけるオープンソースイニシアチブへのご参加をお待ちしております。ぜひ貢献ガイドをご確認ください。