使用適用於 Visual Studio Code 的 Azure API 中心擴充功能建置和註冊 API
若要在 API 中心建置、探索、探索及取用 API,您可以在 Visual Studio Code 開發環境中使用 Azure API 中心延伸模組。 延伸模組為 API 開發人員提供下列功能:
建置 API - 直接在 API 中心註冊 API,或使用 GitHub 或 Azure DevOps 中的 CI/CD 管線,讓 API 可供其他人探索。 在 Visual Studio Code 中早期導入 API 設計一致性檢查,並整合 Lint 分析功能。 透過重大變更偵測,來確定新的 API 版本不會中斷 API 取用者的操作。
探索 API - 瀏覽 API 中心的 API,並檢視其詳細資料和文件。
探索 API - 使用 Swagger UI 或 REST 用戶端來探索 API 要求和回應。
取用 API - 使用為 Microsoft Graph、GitHub 等服務產生 SDK 的 Microsoft Kiota 引擎,為您慣用的語言 (包括 JavaScript、TypeScript、.NET、Python 和 Java) 產生 API SDK 用戶端。
必要條件
Azure 訂用帳戶中的一或多個 API 中心。 如果您尚未建立,請參閱快速入門:建立您的 API 中心。
目前,您必須獲指派參與者角色或更高許可權,才能使用擴充功能管理 API 中心。
適用於 Visual Studio Code 的 Azure API 中心延伸模組
注意
凡註明的地方,某些功能僅適用於延伸模組的發行前版本。 從 Visual Studio Code Marketplace安裝延伸模組時,您可以選擇安裝發行版本或發行前版本。 使用延伸模組檢視中延伸模組的 [管理] 按鈕操作功能表,隨時切換兩個版本。
下列 Visual Studio Code 延伸模組是選擇性的,且僅適用於特定案例,如下所示:
- REST 用戶端延伸模組 - 直接在 Visual Studio Code 中傳送 HTTP 要求及檢視回應
- Microsoft Kiota 延伸模組 - 產生 API 用戶端
- Spectral 延伸模組:在 Visual Studio Code 中執行早期偵測 API 設計一致性檢查
- Optic CLI:偵測 API 規格文件之間的重大變更
- GitHub Copilot:從 API 程式碼產生 OpenAPI 規格檔案
設定
- 從 Visual Studio Code Marketplace 安裝適用於 Visual Studio Code 的 Azure API 中心延伸模組。 視需要安裝選擇性延伸模組。
- 在 Visual Studio Code 左側的 [活動列] 中,選取 [API 中心]。
- 如果您未登入 Azure 帳戶,請選取 [登入 Azure...],並依照提示登入。 選取您要從中檢視 API 的一或多個 API 中心所屬的 Azure 帳戶。 如果有許多要檢視的訂用帳戶,您也可以篩選特定訂用帳戶。
註冊 API
直接從 Visual Studio Code 在 API 中心註冊 API,可透過將 API 註冊為一次性作業,或使用 CI/CD 管線來進行。
使用 Ctrl+Shift+P 鍵盤快速鍵開啟命令選擇區。 輸入 Azure API Center: Register API,然後點擊 Enter。
選取您要向 API 中心註冊 API 的方式:
- 逐步執行最適合單次註冊 API。
- CI/CD 可在您正在使用的 Visual Studio Code 工作區中新增預先設定的 GitHub 或 Azure DevOps 管線,此管線會在每次認可至原始檔控制時,作為 CI/CD 工作流程的一部分執行。 隨著 API 不斷演進,建議您使用 CI/CD 清查 API 中心內的 API,以確保 API 中繼資料 (包括規格和版本) 在 API 中心始終保持最新狀態。
完成註冊步驟:
- 若為逐步執行,請選取 API 中心來註冊 API,並以相關資訊來回答提示,包括 API 標題、類型、生命週期階段、版本和規格,以完成 API 註冊。
- 若為 CI/CD,根據您慣用的原始檔控制機制,選取 GitHub 或 Azure DevOps。 Visual Studio Code 工作區必須開啟,Azure API 中心延伸模組才能將管線新增至工作區。 新增檔案後,請完成 CI/CD 管線檔案本身中所描述的步驟,以設定 Azure Pipeline/GitHub Action 環境變數和身分識別。 在推送至原始檔控制時,會在 API 中心註冊 API。
深入瞭解如何設定 GitHub Actions 工作流程 ,以向 API 中心註冊 API。
API 設計一致性
為了確保設計符合組織標準,建置 API 時,適用於 Visual Studio Code 的 Azure API 中心延伸模組會提供與 Spectral 整合的 API 規格 Lint 分析支援。
- 使用 Ctrl+Shift+P 鍵盤快速鍵開啟命令選擇區。 輸入 Azure API 中心:設定作用中 API 樣式指南,然後按 Enter 鍵。
- 選取其中一個隨附的預設規則,或者,如果您的組織已有可用的樣式指南,請使用 [選取本機檔案] 或 [輸入遠端 URL],在 Visual Studio Code 中指定作用中規則集。 按 Enter 鍵。
設定使用中的 API 樣式指南之後,在 Visual Studio Code 中開啟任何 OpenAPI 或 AsyncAPI 型規格檔案,將會觸發本機的 Lint 分析作業。 結果會在編輯器中內嵌顯示,以及在 [問題] 視窗中顯示 ([檢視] > [問題] 或 Ctrl+Shift+M)。
重大變更偵測
推出新版本的 API 時,請務必確保所做的變更不會導致使用舊版 API 的取用者發生功能中斷的問題。 Visual Studio Code 的 Azure API 中心延伸模組讓這變得簡單,其 OpenAPI 規格文件的重大變更偵測由 Optic 提供技術支援。
- 使用 Ctrl+Shift+P 鍵盤快速鍵開啟命令選擇區。 輸入 Azure API 中心:偵測中斷性變更,然後按 Enter 鍵。
- 選取要比較的第一個 API 規格文件。 有效選項包括位於 API 中心、本機檔案或 Visual Studio Code 作用中編輯器中的 API 規格。
- 選取要比較的第二個 API 規格文件。 有效選項包括位於 API 中心、本機檔案或 Visual Studio Code 作用中編輯器中的 API 規格。
Visual Studio Code 會在兩份 API 規格之間開啟差異檢視。 任何重大變更都會在編輯器中內嵌顯示,以及在 [問題] 視窗中顯示 ([檢視] > [問題] 或 Ctrl+Shift+M)。
從 API 程式碼產生 OpenAPI 規格檔案
將 Azure API 中心延伸模組與強大的 GitHub Copilot 整合使用於 Visual Studio Code,可從 API 程式碼建立 OpenAPI 規格檔案。 以滑鼠右鍵按一下 API 程式碼,從選項中選取 [Copilot],然後選取 [產生 API 文件]。 這會建立 OpenAPI 規格檔案。
注意
此功能適用於 API 中心延伸模組的發行前版本。
產生 OpenAPI 規格檔案並檢查正確性之後,您就可以使用 Azure API Center: Register API 命令向 API 中心註冊 API。
探索 API
您的 API 中心資源會顯示在左側的樹狀檢視中。 展開 API 中心資源以查看 API、版本、定義、環境和部署。
使用 Apis 樹狀檢視項目中顯示的搜尋圖示,在 API 中心內搜尋 API。
提示
選擇性地在Visual Studio Code 中為您的 API 中心啟用 平臺 API 目錄 ,讓組織中的應用程式開發人員可以在集中式位置探索 API。 平臺 API 目錄是 API 清查的唯讀檢視。
檢視 API 文件
您可以在 API 中心檢視 API 定義的文件,並嘗試進行 API 作業。 此功能僅適用於 API 中心的 OpenAPI 型 API。
展開 [API 中心] 樹狀檢視,以顯示 API 定義。
以滑鼠右鍵按一下定義,並選取 [開啟 API 文件]。 新的索引標籤隨即出現,其中包含 API 定義的 Swagger UI。
若要試用 API,請選取端點、選取 [試用]、輸入必要的參數,然後選取 [執行]。
注意
視 API 而定,您可能需要提供授權認證或 API 金鑰,才能試用 API。
提示
您可以使用延伸模組的發行前版本以 Markdown 格式產生 API 文件,這是一種易於維護和與使用者共用的格式。 以滑鼠右鍵按一下定義,並選取 [產生 Markdown]。
產生 HTTP 檔案
您可以根據 API 中心的 API 定義來檢視 .http
檔案。 如果已安裝 REST 用戶端延伸模組,則可從 Visual Studio Code 編輯器提出要求目錄。 此功能僅適用於 API 中心的 OpenAPI 型 API。
展開 [API 中心] 樹狀檢視,以顯示 API 定義。
以滑鼠右鍵按一下定義,並選取 [產生 HTTP 檔案]。 此時會出現新的索引標籤,轉譯由 API 規格填入的 .http 文件。
若要提出要求,請選取端點,然後選取 [傳送要求]。
注意
視 API 而定,您可能需要提供授權認證或 API 金鑰,才能提出要求。
產生 API 用戶端
使用 Microsoft Kiota 延伸模組產生您慣用語言的 API 用戶端。 此功能僅適用於 API 中心的 OpenAPI 型 API。
- 展開 [API 中心] 樹狀檢視,以顯示 API 定義。
- 以滑鼠右鍵按一下定義,並選取 [產生 API 用戶端]。 [Kiota OpenAPI 產生器] 窗格隨即出現。
- 選取要包含在 SDK 中的 API 端點和 HTTP 作業。
- 選取 [產生 API 用戶端]。
用戶端隨即產生。
如需使用 Kiota 延伸模組的詳細資訊,請參閱適用於 Visual Studio Code 的 Microsoft Kiota 延伸模組。
匯出 API 規格
您可以從定義匯出 API 規格,然後將其下載為檔案。
若要在延伸模組的樹狀檢視中匯出規格:
您也可以使用命令選擇區來匯出規格:
- 輸入 Ctrl+Shift+P 鍵盤快速鍵以開啟命令選擇區。
- 選取 [Azure API 中心:匯出 API 規則文件]。
- 進行選取以瀏覽至 API 定義。 隨即會顯示新的索引標籤,以轉譯 API 規格文件。