OpenAPI 仕様とは

OpenAPI 仕様 (旧称 Swagger) では、API のさまざまな側面について説明します。 OpenAPI 仕様 (仕様) では、API のエンドポイント、パラメーター、および応答について説明します。 OpenAPI 仕様は YAML または JSON で記述され、ツールによってドキュメント、テスト ケース、およびクライアント ライブラリを生成するために使用されます。 OpenAPI 仕様を用意することで、API 開発者は、API が正確に記述され、利用しやすく、さまざまなアプリケーションやサービスにわたって簡単に統合できることを確認できます。

API の OpenAPI 仕様を用意することを検討すべき理由を次に示します。

• 標準化された方法で API を文書化します。 一貫性のある人間が判読できる形式で API 仕様を文書化します。
• クライアント SDK を生成します。 Kiota などのツールを使用して、さまざまなプログラミング言語でのクライアント ライブラリの生成を自動化します。
• モック API を作成します。 API 仕様に基づいてモック サーバーを作成します。これは、実際の API がまだ実装されていない開発の初期段階で役立ちます。
• コラボレーションを改善します。 さまざまなチーム (フロントエンド、バックエンド、QA) に API の機能と制限事項を明確に理解してもらうと、新しいチーム メンバーがすぐに追いつくのに役立ちます。
• テストと検証を簡略化します。 仕様に対する API 要求と応答の検証を自動化することで、不一致を識別しやすくなります。
• API 管理ツールと統合します。 Azure API Center や Azure API Management など、多くの API 管理ツールとゲートウェイを使用して、API を簡単に統合、デプロイ、監視できます。
• API ゲートウェイの構成を簡略化します。 OpenAPI 仕様を使用して API ゲートウェイを構成し、ルーティング、変換、クロスオリジン リソース共有設定などのタスクを自動化します。

OpenAPI 仕様を使用すると、適切に設計され、一貫して文書化された API を作成できます。 また、保守性が高く、内部と外部のコンシューマーの両方で使いやすくなっています。

OpenAPI 仕様はまだありませんか？

既に存在する API の仕様を手動で記述するには時間がかかり、実際のAPIの動作から乖離していきます。 もう 1 つのオプションは、API から返された内容を記録し、そこからスペックを生成することです。

開発プロキシは 、アプリと API の間の要求と応答を記録し、そこから OpenAPI 仕様を生成します。 手順については、「OpenAPI 仕様の生成」を参照してください。

次のステップ