微軟宣佈在 Azure API 管理中預覽 OpenAPI 規範 V3
最近,微軟宣佈在 Azure API 管理中支援 OpenAPI 規範 V3,他們的服務允許建立、釋出、監控和維護 API。OpenAPI 規範的使用是通過 OpenAPI .NET SDK 完成的,並支援從它們的實現中抽象出 API 定義。
OpenAPI 規範(以前稱為 Swagger)提供了以獨立於語言的方式描述 RESTful Web 服務的方法。隨著 OpenAPI 的廣泛採用,已經形成了一個多樣化的生態系統,我們可以使用各種工具來設計、記錄、構建、測試和實現治理。該規範受 Linux 基金會下屬的 OpenAPI Initiative 監督,並有各種各樣的組織推動其開發,包括 SmartBear、微軟和 WSO2 等公司。任何人都可以在 OpenAPI Initiative 的 GitHub 儲存庫上跟蹤甚至參與規範的開發。
根據微軟 Azure MVP 和 Azure 架構師 Tom Kerkhove 的說法,在向消費者公開 API 時,規範扮演著重要的角色。
API 必須乾淨整潔且文件良好。這讓你的消費者可以知道你提供了哪些功能、它們的用途以及可以有怎樣的期望。這就是 OpenAPI 規範(又名 Swagger)的作用所在,它定義了應該如何在整個行業中定義 API,而不管其背後的技術是什麼。
規範的版本 3 帶來了一些變化,現在 Azure API 管理也已經支援這些變化。例如,這個新版本引入了一個包含諸如訊息頭、連結和回撥等元件的全新體系結構,在定義中採用了更加模組化的方法,RestCase 執行長 Guy Levin 對此進行了描述。
3.0 版本的 API 規範格式採用一種更加模組化且可重用的方法定義 API 表面(surface area),提供了更強大的請求和響應模型描述能力和靈活性,並詳細描述了構成 API 用法的通用元件,如底層資料模式和安全定義。
引入的另一個選項是在操作中包含 callbacks,這意味著現在可以定義 webhook。最後,連結(linking)使我們可以定義 API 的不同路徑之間的關係,提供了屬性擴充套件能力。
隨著公告發布,現在已經可以在 Azure API 管理中匯入 OpenAPI V3 定義,儘管有一些限制。目前,既可以通過門戶,也可以通過 REST API。接著,匯出 OpenAPI 描述的功能也已經可用,可以通過開發者門戶,或使用另一個 REST API 呼叫。
最終,這些功能將正式釋出,使用 PowerShell SDK 進行定義的匯入和匯出也會成為可能。
檢視英文原文:
https://www.infoq.com/news/2019/01/openapi-v3-support-azure-apim