跳至主要内容

暴露操作

規範中並非每個操作都應公開。管理介面、內部工具和草稿操作往往需要保留在文件中,但對已發布文件和 MCP 隱藏。暴露配置讓這一選擇明確,且不修改來源文件。

工作方式​

暴露配置與規範分開儲存。每條記錄引用一個操作並記錄它是否啟用:

  • 存在時優先使用操作的 operationId;
  • 同時儲存 method 和 path,用於沒有操作 ID 的規範以及校驗。

原始文件保持不動。文件和 MCP 由規範結合已啟用操作產生,因此停用某個操作會把它從已發布面移除,而不從你的檔案中刪除。

暴露工作區​

暴露操作形態為處理大型規範而建構:

  • 搜尋——按方法、路徑、摘要或標籤過濾操作;
  • 按標籤分組——操作按其主要標籤分組,未打標籤的操作歸入未分組;
  • 單獨切換——開啟或關閉單個操作;
  • 按組批量——一次啟用或停用某個標籤組中的所有操作;
  • 全選(已過濾)——全域複選框套用於當前匹配搜尋的操作。

每個操作一行,即使操作帶有多個標籤,啟用狀態也保持明確。

實用預設​

一個簡單直接的做法是從全部啟用開始,再停用你不想公開的操作:

  • 內部和管理介面(例如使用者管理或內部健康檢查);
  • 仍在設計中的操作;
  • 僅用於本機除錯的介面。

由於選擇獨立於文件,你可以隨 API 演進而變更它,無需編輯規範本身。

暴露與發布如何相互作用​

暴露決定出現哪些操作;其他控制決定文件是否根本可達:

  • 文件必須為 ACTIVE;
  • 文件和 MCP 各有啟用標記;
  • 存取可由檢視密碼(文件)或存取密鑰(MCP)把關。

完整把關項參見存取控制。

計畫額度​

各計畫限制暴露操作數量:

  • Free(免費)——最多 10 個;
  • Pro——最多 1,000 個;
  • Team——最多 10,000 個。

相關:存取控制、文件與版本。