SwaggerのOpenAPI 3.1サポート発表に続き、OpenAPI 3.1の初期サポートを開始したことをお知らせできることを嬉しく思います。
要するに、SwaggerHubでできるようになりました。
- SwaggerHubを唯一の真の情報源として使用し、OpenAPI 3.1 APIをカタログ化する。
- より強力になった新しいSwagger EditorでOpenAPI 3.1 APIを設計する。
- OpenAPI 3.1およびAsyncAPIを使用しているものを含め、すべてのAPIのドキュメントを保持する。
- JSONスキーマ2012-12のサポートなど、OpenAPI 3.1の新機能を活用する。
このリリースはSwaggerHubにとって始まりにすぎず、OpenAPI 3.1の完全なサポートを近日中に提供することをお約束します。以下に上記の詳細と、完全なAPI開発および管理ワークフローのためのOpenAPI 3.1との機能パリティ計画を記載します。
SwaggerHub OAS 3.1ドキュメントを表示
SwaggerHubにおけるOpenAPI 3.1のサポート構築
単なる「ドットワン」の追加はマイナーリリースに見えるかもしれませんが、モデルとスキーマ、つまりAPIを介してリクエストとレスポンスでやり取りされるJSON、XML、フォームボディの形状を記述する方法の大きな分離を伴います。
OpenAPI 3.1は、JSON Schemaの全範囲（特に執筆時点での最新版であるJSON Schema Draft 2020-12）をサポートしており、論理的にはあらゆるバージョンのJSON Schemaをサポートしています（ただし、ツールメーカーとして、Swaggerではこれをある程度制限しています。サポートされていないものについては以下を参照してください）。
これは何を意味するのでしょうか？
これまで、OpenAPIはJSON Schemaのサブセットをサポートし、同じキーワードに対して異なるセマンティクスを持っていました。これは、スキーマを再利用するには、「OpenAPIフレーバーのJSON Schema」とJSON Schemaの他のバージョン間で変換する必要があることを意味し、スキーマの真の情報源を記述する能力を低下させ、再利用を制限していました。
また、OpenAPIは、JSON Schemaのどの機能をサポートするかについて保守的でした。これは、OpenAPIを完全にサポートできたツールメーカーにとっては良かったのですが、実際のAPIを記述する上でより強力な機能を可能にする機能を残していました。
OpenAPIがJSON Schemaの完全なサポートに譲歩した今、2つのことが期待できます。
- JSON Schemaがいかに強力で洗練されているかを考えると、ツールが機能パリティに達するまでのゆっくりとした立ち上げ。
- OpenAPI、AsyncAPI、JSON Schemaツール、そして潜在的に他の仕様間の再利用性の爆発。
SwaggerとSwaggerHubはどこにいるのか？
オープンソースでは、様々なSwaggerプロジェクトがOpenAPI 3.1をサポートするために、コアのJavaおよびJavaScriptライブラリから、Swagger EditorやSwagger UIなどのユーザー向けツールに至るまで、段階的に、時には完全に書き直されてきました。特に注目すべき例外として、Swagger Codegenの作業は続いています。詳細はこちら: SwaggerはOAS 3.1をサポート。
SwaggerHubでのOAS 3.1におけるRESTful APIのカタログ化
SwaggerHubは、カタログ化機能でOpenAPI 3.1の完全なサポートを誇りに思っています。
これまで、チームがOAS 3.1でAPIの作成を開始していても、それらをSwaggerHubに保存することはできませんでした。しかし、今日これが変わります。OAS 3.1 APIをSwaggerHubに作成またはインポートして、すべてのAPIポートフォリオ管理のための単一の真の情報源を持つことができます。
その3つの例は次のとおりです。
- OpenAPI 3.1定義を作成、検索、フィルタリングします。
- より強力になった新しいSwagger EditorでOpenAPI 3.1定義を設計します。
- カスタムリンティングルールでOpenAPI 3.1を標準化します。
- もちろん、インタラクティブなドキュメントでドキュメントの表示と試用を行います。
SwaggerHubを使用する利点は、これらの異なるAPIのカタログ化を一元化し、共同作業ワークフローをサポートし、標準化とガバナンスを通じてコストを削減することです。RESTful APIとイベント駆動型APIを近くに保つことは、ポートフォリオを管理する上で重要なステップです。
この単一のAPIカタログにより、開発者、アーキテクト、デザイナー、消費者など、誰もが発見性の向上とガバナンスの強化の恩恵を受けることができます。
詳細を見る
SwaggerHubによるOAS 3.1でのRESTful APIの設計
2022年後半に発表された新しいSwagger Editorは、OpenAPI 3.1でRESTful APIの設計をサポートする現在の状況に至るまでの画期的な出来事でした。新しいEditorの大きな進歩は、複数のAPI仕様をサポートしつつ、拡張の容易さも確保できる点です。
現在、OAS 3.1でRESTful APIを作成、ドキュメント化、テストしながら、現在のベストプラクティスと標準を維持することができます。
新しいSwagger Editorを始めましょう
SwaggerHubによるOAS 3.1でのRESTful APIのドキュメント化
SwaggerHubでは、OAS 3.1仕様で作成されたAPIの正確で最新のドキュメントを維持できます。設計中にインタラクティブなドキュメントを自動的に生成するため、APIの消費者と社内ユーザーの両方がAPIについて学び、作業することができます。
OAS 3.1 APIとAsyncAPI定義を1つの中央プラットフォームにインポートまたはホストし、ドキュメントのバージョン管理と公開を管理して一貫性を確保します。
詳細を見る
次は何ですか？
この最初のリリースは当社の出発点です。SwaggerHub全体でOAS 3.1のサポートを拡大することをお約束します。次に、コラボレーションと統合をさらに進めるなど、APIのライフサイクルを効果的に管理するために必要な重要な機能をさらに構築していきます。