Azure API Management は、API の記述に広く使われているオープンソース仕様の最新バージョンである OpenAPI 仕様 v3 のプレビュー サポートを導入しました。機能の実装は OpenAPI.NET SDK に基づいています。

このブログ投稿では次の項目を説明します。

• API に OpenAPI 仕様を使う利点。
• Azure API Management で OpenAPI 仕様のドキュメントから API を作成する方法。
• OpenAPI 仕様のドキュメントとして API をエクスポートする方法。
• 正式版リリースに向けて残っている作業。

API に OpenAPI 仕様を使う理由

OpenAPI 仕様は広く採用されている業界標準です。OpenAPI イニシアチブは、Microsoft などの大企業を含む 30 を超える企業に支持されています。

OpenAPI 仕様を使うと、実装環境から API を分離できます。API の定義は言語の影響を受けません。

また、わかりやすく明確です。API が YAML ファイルまたは JSON ファイルで表現され、人も機械も読むことができます。

OpenAPI 仕様が広く採用された結果、広範なツール エコシステムが作られました。ツールの機能は、API 設計協力プロセスが容易になることから、普及しているプログラミング言語でクライアントの SDK およびサーバー実装を自動的に生成できることにまで及びます。

Azure API Management で OpenAPI 仕様 v3 の定義をインポートする方法

API が OpenAPI 仕様ファイルで定義されていると、Azure API Management で API を簡単にインポートできます。Azure ポータルは、正しいバージョンの OpenAPI 仕様ファイルを自動的に認識します。ビジュアル インターフェイスを使って API をインポートする方法については、チュートリアル　"Import and publish your first API" (最初の API のインポートと発行) をご覧ください。

または、contentFormat ペイロード パラメーターを openapi、openapi+json、または openapi-link に設定した状態で REST API コールを使用して API をインポートできます。

インポート中、仕様の servers フィールドに複数のエントリが含まれている場合、API Management は最初の HTTPS URL を選びます。HTTPS URL がない場合は、最初の HTTP URL が選ばれます。HTTP URL がない場合は、バックエンド サービスの URL は空になります。

インポート機能にはいくつかの制限があります。例えば、examples フィールドおよび multipart/form-data フィールドはサポートされません。

Azure API Management で OpenAPI 仕様 v3 の定義をエクスポートする方法

Azure API Management では、OpenAPI 仕様 v3 のフォーマットで API を簡単にエクスポートできます。

API 仕様は、開発者ポータルから JSON ファイルまたは YAML ファイルとしてダウンロードできます。開発者ポータルは、自動的に生成される、完全にカスタマイズできる Web サイトです。ここにアクセスすると、API を見つけ、その使用方法を学習し、インタラクティブに試し、最後にサイン アップして API キーを取得できます。

Azure ポータルのビジュアル インターフェイスからまたはフォーマット クエリ パラメーターを openapi-link に設定した状態で REST API コールを使って仕様をエクスポートすることもできます。

使用開始方法と次の作業

OpenAPI 仕様ファイルから API をインポートすることによって、数分で現在の機能を試すことができます。機能を正式版にする前に、REST API コールを使った JSON フォーマットのエクスポートを実装します。数か月以内に、PowerShell SDK でも OpenAPI 仕様 v3 のインポートとエクスポートのサポートを追加します。

ご意見をお寄せください。