> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/openapi/guides/structuring-your-api-reference.md).
# 组织你的 API 参考
GitBook 不仅仅是渲染你的 OpenAPI 规范。它还让你自定义 API 参考文档，以获得更好的清晰度、导航和品牌展示。
要在以下之间进行选择 **每个标签一页** 并 **每个操作一页**，请参见 [OpenAPI 布局](/docs/documentation/zh/chuang-jian-nei-rong/openapi/guides/openapi-layouts.md).
本页说明如何使用标签控制生成的导航。
### 使用标签组织生成的页面
GitBook 使用标签在两种布局中组织生成的 API 参考页面。
使用 **每个标签一页**，GitBook 会为每个标签创建一个页面。使用 **每个操作一页**，GitBook 会为每个操作创建一个页面，并使用标签在目录中对这些页面进行分组。
要将相关操作分组，请为每个操作分配相同的标签：
paths:
/pet:
put:
标签：
- pet
summary: 更新现有宠物。
description: 通过 Id 更新现有宠物。
operationId: updatePet
### 重新排序目录中的页面
生成的标签页或标签组的顺序与 OpenAPI 中标签的顺序一致 `标签` array:
标签：
- name: pet
- name: store
- name: user
### 将页面嵌套为分组
要构建多级导航，请在标签中使用 `x-parent` （或 `parent`）来定义层级结构。这适用于两种页面结构：
标签：
- name: everything
- name: pet
x-parent: everything
- name: store
x-parent: everything
上面的示例会创建如下目录：
```
全部
├── 宠物
└── 商店
```
如果 GitBook 生成了父页面，而该页面没有描述，则会为其子页面显示基于卡片的布局。
### 自定义页面标题、图标和描述
你可以通过 `标签` 部分。所有 [Font Awesome 图标](https://fontawesome.com/search) 都支持，可通过 `x-page-icon`.
{% code title="openapi.yaml" %}
```yaml
标签：
- name: pet
# 目录和页面中显示的页面标题
x-page-title: Pet
# 目录中以及页面标题旁显示的图标
x-page-icon: dog
# 显示在标题上方的描述
x-page-description: 宠物太棒了！
# 页面内容
description: 关于你的宠物的一切
```
{% endcode %}
### 使用 GitBook Blocks 构建丰富的描述
标签描述字段支持 GitBook Markdown，包括 [高级区块](/docs/documentation/zh/chuang-jian-nei-rong/blocks.md) 例如选项卡：
{% code title="openapi.yaml" %}
```yaml
---
标签：
- name: pet
description: |
这里是宠物的详细信息。
{% tabs %}
{% tab title="狗" %}
这里是狗
{% endtab %}
{% tab title="猫" %}
这里是猫
{% endtab %}
{% tab title="兔子" %}
这里是兔子
{% endtab %}
{% endtabs %}
```
{% endcode %}
### 突出显示 Schemas
你可以使用 GitBook Markdown 在 GitBook 描述中突出显示一个 schema。下面是一个示例，它会突出显示“petstore”规范中的“Pet”schema：
{% code title="openapi.yaml" %}
```yaml
---
标签：
- name: pet
description: |
{% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
Pet 对象
{% endopenapi-schemas %}
```
{% endcode %}
### 为 webhook 端点编写文档
GitBook 支持 OpenAPI 3.1，包括 webhook 端点。
该 `webhooks` 字段是 OpenAPI 3.1 的一部分，因此你的规范必须声明 OpenAPI 3.1 版本。你可以直接在 OpenAPI 文件中定义 webhook，GitBook 会将它们与其他 API 操作一起渲染。有关跨 OpenAPI 文档的版本支持，请参见 [OpenAPI 兼容性](/docs/documentation/zh/chuang-jian-nei-rong/openapi.md#openapi-compatibility).
{% code title="openapi.yaml" %}
```yaml
---
openapi: 3.1.0 # Webhooks 从 OpenAPI 3.1 起可用
webhooks:
newPet:
post:
summary: 新宠物事件
description: 系统中新宠物的信息
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
responses:
"200":
description: 返回 200 状态，以表明数据已成功接收
```
{% endcode %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/openapi/guides/structuring-your-api-reference.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.