管理页面可见性

通过隐藏、过滤或整理自动生成的 OpenAPI 页面，控制哪些 API 端点出现在文档导航中。

对于仅供内部使用的端点、已弃用的操作、测试版功能，或那些应可通过直接 URL 访问但不应通过站点导航被发现的端点，你可以控制哪些 OpenAPI 操作会发布为文档页面，以及它们在导航中的可见性。

如果你的页面是由 OpenAPI 文档自动生成的，请使用 x-hidden 和 x-excluded 扩展来管理页面可见性。

​

x-hidden

x-hidden 扩展会为某个端点创建页面，但会将其从导航中隐藏。该页面只能通过直接访问其 URL 来查看。

x-hidden 的常见用例包括：

• 需要记录但不希望在导航中曝光的端点。
• 从其他内容中链接到的页面。
• 面向特定用户的端点。

​

x-excluded

x-excluded 扩展会将某个端点从文档中彻底排除。

x-excluded 的常见用例包括：

• 仅供内部使用的端点。
• 已废弃且不再希望出现在文档中的端点。
• 尚未对外公开文档的 Beta 功能。

​

实现

在 OpenAPI 规范中，在相应的 HTTP 方法下添加 x-hidden 或 x-excluded 扩展。

以下示例展示了在 OpenAPI 架构文档中，如何在某个端点和一个 webhook 路径上使用这些属性。

Endpoint example

"paths": {
  "/plants": {
    "get": {
      "description": "返回商店中的所有植物",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/hidden_plants": {
    "get": {
      "x-hidden": true,
      "description": "返回商店中的所有半保密植物",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  },
  "/secret_plants": {
    "get": {
      "x-excluded": true,
      "description": "返回商店中的所有绝密植物（请勿发布此端点！）",
      "parameters": { /*...*/ },
      "responses": { /*...*/ }
    }
  }
},

Webhook example

"webhooks": {
  "/plants_hook": {
    "post": {
      "description": "关于商店新增植物信息的 Webhook",
    }
  },
  "/hidden_plants_hook": {
    "post": {
      "x-hidden": true,
      "description": "关于商店新增植物的部分机密信息的 Webhook"
    }
  },
  "/secret_plants_hook": {
    "post": {
      "x-excluded": true,
      "description": "关于商店新增植物的绝密信息的 Webhook(请勿发布此端点!)"
    }
  }
}