先日Microsoftは、APIのセットアップ、公開、モニタリング、保守を可能にするAzure API ManagementでOpenAPI仕様のv3をサポートすると発表した。OpenAPI仕様のサポートは、OpenAPI.NET SDKを通じて実装されていて、その実装からAPI定義が抽象化できる。
OpenAPI仕様は以前はSwaggerと呼ばれており、言語に依存しないRESTful webサービスを記述うsるための手段を提供する。OpenAPIは広く採用されており、設計、ドキュメント化、構築、テスト、ガバナンスの実装のためのツールを備えた多様なエコシステムが利用できる。この仕様はLinux Foundationが所有するOpenAPIイニシアチブによって管理されており、SmartBear、Microsoft、WSO2などの企業を含む広く様々な組織が開発している。誰でもOpenAPIイニシアチブのGitHubリポジトリにある仕様をフォローして、開発に貢献できる。
Microsoft Azure MVPでAzure ArchitectのTom Kerkhove氏によると、彼らの顧客にAPIを公開するときに、この仕様は重要な役割を果たす。
明確で文書化されたAPIを提供することは必須です。これにより利用者は提供される機能を知ることができ、期待できる機能を知ることができます。OpenAPI仕様、別名Swaggerが登場し、基盤となる技術に関係なく、業界を横断してAPIを定義できるようになりました。
バージョン3仕様では、いくつかの変更があり、Azure API Managementでもすでに利用できる。 例えば、この新しいバージョンではヘッダ、リンク、コールバックなどコンポーネントによる新しいアーキテクチャが導入されている。定義のモジュラーアプローチについてRestCaseのCTOであるGuy Levin氏は説明する。
バージョン3のAPI仕様フォーマットは、モジュラー化が進み、APIの表面領域定義の再利用可能なアプローチが採用され、リクエストとレスポンスのモデルの記述と、基礎となるデータスキーマとセキュリティ定義のようなAPIの使用法を構成する一般的なコンポーネントの詳細を提供し、さらなるパワーと多様性が可能になりました。
もう一つの導入されたオプションには、操作へのコールバックとして、webhooksを記述できるようになった。最後に、異なるパスのAPI間の関係をリンクで定義でき、属性で拡張する機能を提供できる。
画像のソース: https://blog.restcase.com/6-most-significant-changes-in-oas-3-0/
発表後、Azure API ManagementでOpenAPI v3定義のインポートができるようになったが、いくつかの制限がある。現在、ポータルまたはREST APIを通じて可能だ。その後、開発者ポータルか、REST APIへの別の呼び出しを使用して、OpenAPI記述の公開機能も利用できる。
これらの機能が一般利用可能になる前に定義のインポートとエクスポートの両方がPowerShell SDKからも利用可能になる。