小さな反骨精神のオープンソースプロジェクトが、業界全体の認識を変えていく様子を見るのは実に魅力的です。これは、オープンソースのAPI設計標準であるSwagger Specificationで起こったことです。Swagger Specificationは、開発者のコミュニティ全体を育成し、強力なツールエコシステムを築き、最終的にはRESTfulサービスを定義する世界標準であるOpenAPI Specification (OAS)へと進化しました。Swagger Specificationの初期バージョンを開発した企業およびチームとして、このイノベーションの一翼を担えたことを光栄に思います。本日、SwaggerHubにおけるOpenAPI Specificationの次期バージョン、3.0のサポートを発表できることを嬉しく思います。
なぜOpenAPI Specification 3.0なのか
OAS 3.0は、豊かで表現力豊かな多様な機能をAPI設計の最前線にもたらします。構造ははるかにシンプルに再構築されました。例えば、パラメータ、レスポンス、例などの再利用可能なオブジェクトはすべてコンポーネントオブジェクトの下にまとめられ、紛らわしいボディパラメータはrequestBodyに置き換えられ、formDataもその下にグループ化されます。また、リンキング、コールバック、複数のサーバホスト、より優れたセキュリティ定義など、新しい機能が多数追加されました。これらの新しい変更点の詳細については、今後のトレーニングで学ぶことができます。
OpenAPI 3.0: 最新のOpenAPI SpecificationでAPIを設計し、ドキュメント化する方法。OAS 3.0の豊富な記述セットにより、アーキテクト、開発者、テクニカルライターは、制限なくAPIをより適切に記述でき、消費体験が向上します。業界はOAS 3.0の採用を進めており、仕様を中心に新しいツールが開発されています。先月、私たちは
Swagger EditorとUI、および
Swagger CoreでOAS 3.0のサポートを提供し、これはSwaggerHubにも拡張され、チームはOAS 3.0を使用してAPI設計およびドキュメントプロセスで協力できるようになりました。
SwaggerHubが提供できるものとは？
設計とドキュメンテーション
SwaggerHubエディタは、REST APIの設計とドキュメンテーションのためにOAS 3.0をサポートしています。つまり、APIを設計する際にエディタのオートコンプリート、エラーフィードバック、構文検証を活用できると同時に、OAS APIを視覚化できます。SwaggerHubはOASで定義されたAPIのドキュメンテーションを自動生成してホストするため、API設計とドキュメンテーションのすべてのニーズに対応する単一のプラットフォームを提供します。新しいAPIを作成する際には、使用する仕様のバージョンを指定できるため、ニーズに最適な仕様でAPIを柔軟に定義できます。SwaggerHubは、定義をインポートすることを選択した場合、仕様のタイプを自動的に判断することもできます。OAS3.0バッジを使用すると、APIがSwaggerHubの最新OASで定義されているかどうかを簡単に識別できます。
SwaggerからOAS 3.0への変換
新しいフレームワークのバージョンが導入されるたびに最大の課題の1つは移行です。SwaggerHubは、既存のSwagger 2.0仕様を最新のOAS 3.0に変換する機能であなたをサポートします。この即時変換により、APIの新しいバージョンが
-oas3 のサフィックスで作成されます。元のAPIバージョンは変更されません。
これは、API定義のすべての行を解読して変更するために何時間も費やしたり、最新バージョンにアップグレードするためにプラグインを介してAPIを調整したりする必要がなくなったことを意味します。変換ボタンをクリックするだけで、定義がOAS 3.0に変換されます。
素晴らしい！なぜOAS 3.0のサポートはまだベータ版なのですか？
OAS 3.0を使用してAPIの設計、ドキュメント化、変換、共同作業において優れたサポートを提供していますが、OAS 3.0の完全なサポートを提供するために、まだいくつかの追加機能に取り組んでいます。これには以下が含まれます。
- OAS3.0ベースのAPIのドキュメントをインタラクティブにする
- OAS 3.0ベースのAPIのモック機能を有効にする
- OAS 3.0 APIからサーバコードとクライアントSDKを生成する
- SwaggerHubドメインにOAS3.0サポートを追加する
とはいえ、上記の機能はできるだけ早く追加できるよう積極的に取り組んでいます。ユーザーからのフィードバックや機能リクエストはいつでも歓迎しておりますので、OAS 3.0サポートに関するご意見は
[email protected]まで直接メールでお寄せください。
OAS 3.0の使用方法については、ヘルプドキュメントで詳しく学ぶことができます。 OpenAPI 3.0を始めましょう
SwaggerHubのOpenAPI 3.0を使用して、新規および既存のAPIの設計とドキュメント化を開始できます。SwaggerHubエディタを使用すると、OpenAPI 3.0を使用してAPIを定義および視覚化したり、Swagger 2.0で定義された既存のAPIを最新バージョンの仕様に変換したりできます。
今すぐ始めましょう。