誰もがOpenAPI 3.0について話しています。あなたの上司はおそらくアナリストが参照しているのを聞いたでしょうし、近くのクールなスタートアップの友人たちはマイクロサービスベースのアプリケーションをより良く定義するためにそれを使っています。そして、あなたのプロダクトマネージャーのいとこは、去年の感謝祭にAPIの利用がいかに簡単になったかについて熱心に話していました。
興味をそそられ、いくつかの調査の結果、OAS 3.0でAPIを定義することがいかに有益であるかを実感しました。しかし、OpenAPIを絶賛している人々が、APIを実装する前に仕様でAPIを設計していたとしたらどうでしょう？あなたの会社には、OpenAPIが登場するずっと前に実装され展開された、何十ものレガシーAPIがあります。
では、既存のAPIからOpenAPIドキュメントを作成するにはどうすればよいでしょうか？
この仕様を生成するのに最適なプラグインを何時間もかけて調査し、プラグインが実装言語をサポートしていることを確認し、その後、各APIエンドポイントにこのプラグインで注釈を付けるのにさらに時間を費やして、ようやくこの仕様を作成することができます。あるいは、Swagger Inspectorの最新のサポートを利用して、数回クリックするだけでOpenAPI 3.0ドキュメントを生成することができます。
OpenAPI 3.0の簡素化
OpenAPIは、REST APIの状況を永遠に変えました。人間とマシンがAPIを理解し、操作し、消費するための共通のフレームワークを提供しました。開発者がAPIを簡単に構築するための標準テンプレートとして機能し、さまざまなリソースとそれに関連するリクエストとレスポンスのサイクルを詳細に記述します。OpenAPI 3.0は、以前のSwagger 2.0仕様に加えて、豊富な追加機能をもたらします。その中には、次のようなものがあります。
- 仕様の全体的な構造が、より良い再利用性のためにリファクタリングされました
- コールバック記述のサポートを追加
- 操作間の関係を表現するためのリンク
- JSONスキーマには、oneOf、anyOf、notのサポートが含まれます
- スキーマを使用する機能を含む、改善されたパラメータの説明
- マルチパートドキュメント処理のサポートの向上
- クッキーパラメータの追加。データフォームパラメータの削除
- ボディパラメータが独自のエンティティを持つようになりました
- コンテンツタイプネゴシエーションのサポートの向上
- セキュリティ定義が簡素化され、強化されました
OpenAPI 3.0定義は、インタラクティブで使いやすいドキュメントの作成、クライアントSDKのプロトタイピング、テストケースの生成など、さまざまなAPIライフサイクルプロセスを自動化するのに役立ちます。
誰もがOpenAPI 3.0を最大限に活用しようと常に考えており、明らかにAPIには優れた機能があります。しかし、Swagger Inspectorの新しいOAS 3.0サポートは、これらすべてとどのような関係があるのでしょうか？
既存のAPIからOpenAPI 3.0を即座に生成
デザインファーストアプローチは、実際のコード、実装、テスト、ドキュメント作成を行う前に、OpenAPI仕様でAPIを設計することを提唱しています。しかし、デザインファーストアプローチは、すべての開発者が目指すべき理想的なものですが、常に簡単に達成できるわけではありません。
多くの場合、組織にはすでに実装されデプロイされている既存のAPIが多数存在し、何の定義もありません。また、企業やチームが今後APIプログラムでAPIを最初に設計しない実用的な理由もたくさんあります。
ここでInspectorの出番です。Swagger Inspectorを使用すれば、時間のかかるコードファーストのOpenAPI生成のジレンマに別れを告げることができます！Inspectorを使用すると、数回クリックするだけで、既存のAPIエンドポイントから数分でOpenAPI定義を生成できます。これを行うには、OpenAPIで定義したいAPIのベースURIとパスをフォームフィールドに挿入します。必要に応じて、認証、ヘッダー、またはクエリパラメータをいつでも追加してから、SENDを押すことができます。
有効なレスポンスを受け取ったら、履歴タブの下の右側のパネルからOpenAPIファイルを生成できます。Inspectorの素晴らしい点は、複数のエンドポイントを単一のOpenAPIファイルに統合できることです。これは自動的にSwaggerHubにプッシュされます。SwaggerHubは、設計およびドキュメントプラットフォームであり、ドキュメントのさらに編集、クライアントSDKの生成、インタラクティブなドキュメントの作成などを行うことができます。
OpenAPIエンドポイントの簡単な解析とテスト
開発者は、開発プロセス中にAPIとエンドポイントが意図したとおりに機能するかどうかを常に再確認する必要があります。誰も新しいプロセスを好みません。特に開発者はそうです。
OpenAPIで既に定義されているAPIを使用している開発者向けに、Swagger InspectorはOpenAPI 3.0ファイルを簡単に解析し、API全体でさまざまなエンドポイントとメソッドを確認できるため、テストしたいリソースを選択できます。
API定義の場所を挿入するか、OpenAPIファイルをアップロードするだけです。たとえば、SmartBear Petstore APIがOAS 3.0で定義されている場所はSwaggerHubにあります。この場所をInspectorに挿入し、SENDを押すだけです。有効なOpenAPI 3.0定義である場合、USE DEFINITIONボタンでAPIのすべてのエンドポイントを確認できます。
ここから、検証したいエンドポイントとメソッドを選択し、レスポンスが期待どおりかどうかを確認できます！
最後に、履歴タブでテストしたエンドポイントを選択してください。そこから、「CREATE API DEFINITION」ドロップダウンをクリックし、OAS 3.0を選択します。定義の生成を完了するには、アカウントを作成する必要があります。
OpenAPIを知っていると言うとき、私たちは本気です。OASは、API開発を推進し加速するための最高のオープンスタンダードであり、Swagger InspectorがOAS 3.0仕様を簡単に開始する方法を提供できることを願っています。
お読みいただきありがとうございます！APIリソースをもっとお探しですか？Swaggerニュースレターを購読してください。毎月、最高のAPI記事、トレーニング、チュートリアルなどが記載されたメールが届きます。 購読