mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
151a22517f
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
92 lines
2.6 KiB
Plaintext
92 lines
2.6 KiB
Plaintext
---
|
|
title: "管理页面可见性"
|
|
description: "控制哪些 API 端点显示在文档导航中。"
|
|
keywords: ["x-hidden", "x-excluded", "隐藏端点", "页面可见性", "内部端点"]
|
|
---
|
|
|
|
对于仅供内部使用的端点、已弃用的操作、测试版功能，或那些应可通过直接 URL 访问但不应通过站点导航被发现的端点，你可以控制哪些 OpenAPI 操作会发布为文档页面，以及它们在导航中的可见性。
|
|
|
|
如果你的页面是由 OpenAPI 文档自动生成的，请使用 `x-hidden` 和 `x-excluded` 扩展来管理页面可见性。
|
|
|
|
<div id="x-hidden">
|
|
## `x-hidden`
|
|
</div>
|
|
|
|
`x-hidden` 扩展会为某个端点创建页面，但会将其从导航中隐藏。该页面只能通过直接访问其 URL 来查看。
|
|
|
|
`x-hidden` 的常见用例包括：
|
|
|
|
- 需要记录但不希望在导航中曝光的端点。
|
|
- 从其他内容中链接到的页面。
|
|
- 面向特定用户的端点。
|
|
|
|
<div id="x-excluded">
|
|
## `x-excluded`
|
|
</div>
|
|
|
|
`x-excluded` 扩展会将某个端点从文档中彻底排除。
|
|
|
|
`x-excluded` 的常见用例包括：
|
|
|
|
- 仅供内部使用的端点。
|
|
- 已废弃且不再希望出现在文档中的端点。
|
|
- 尚未对外公开文档的 Beta 功能。
|
|
|
|
<div id="implementation">
|
|
## 实现
|
|
</div>
|
|
|
|
在 OpenAPI 规范中，在相应的 HTTP 方法下添加 `x-hidden` 或 `x-excluded` 扩展。
|
|
|
|
以下示例展示了在 OpenAPI 架构文档中，如何在某个端点和一个 webhook 路径上使用这些属性。
|
|
|
|
```json Endpoint example {11, 19}
|
|
"paths": {
|
|
"/plants": {
|
|
"get": {
|
|
"description": "返回商店中的所有植物",
|
|
"parameters": { /*...*/ },
|
|
"responses": { /*...*/ }
|
|
}
|
|
},
|
|
"/hidden_plants": {
|
|
"get": {
|
|
"x-hidden": true,
|
|
"description": "返回商店中的所有半保密植物",
|
|
"parameters": { /*...*/ },
|
|
"responses": { /*...*/ }
|
|
}
|
|
},
|
|
"/secret_plants": {
|
|
"get": {
|
|
"x-excluded": true,
|
|
"description": "返回商店中的所有绝密植物（请勿发布此端点！）",
|
|
"parameters": { /*...*/ },
|
|
"responses": { /*...*/ }
|
|
}
|
|
}
|
|
},
|
|
```
|
|
|
|
```json Webhook example {9, 15}
|
|
"webhooks": {
|
|
"/plants_hook": {
|
|
"post": {
|
|
"description": "关于商店新增植物信息的 Webhook",
|
|
}
|
|
},
|
|
"/hidden_plants_hook": {
|
|
"post": {
|
|
"x-hidden": true,
|
|
"description": "关于商店新增植物的部分机密信息的 Webhook"
|
|
}
|
|
},
|
|
"/secret_plants_hook": {
|
|
"post": {
|
|
"x-excluded": true,
|
|
"description": "关于商店新增植物的绝密信息的 Webhook(请勿发布此端点!)"
|
|
}
|
|
}
|
|
}
|
|
```
|