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 を作成できます。 また、保守性が高く、内部と外部のコンシューマーの両方で使いやすくなっています。

API の OpenAPI 仕様がない場合は、Dev Proxy を使用して、インターセプトされた要求と応答から 1 つを生成できます。

次のステップ

OpenAPI 仕様を生成する