> 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/api-references/guides/structuring-your-api-reference.md).

# 组织你的 API 参考文档

GitBook 不仅仅会渲染你的 OpenAPI 规范。它还让你自定义 API 参考文档，以获得更好的清晰度、导航和品牌呈现。

在……之间选择 **每个标签一页** 和 **每个操作一页**，请参见 [OpenAPI 布局](/docs/documentation/zh/api-references/guides/openapi-layouts.md).

本页说明如何使用标签控制生成的导航。

### 使用标签来组织生成的页面

GitBook 使用标签在这两种布局中组织生成的 API 参考页面。

使用 **每个标签一页**，GitBook 会为每个标签创建一页。使用 **每个操作一页**，GitBook 会为每个操作创建一页，并使用标签在目录中对这些页面分组。

要将相关操作分组，请为每个操作分配相同的标签：

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">paths:
  /pet:
    put:
<strong>      tags:
</strong><strong>        - pet
</strong>      summary: 更新现有宠物。
      description: 按 ID 更新现有宠物。
      operationId: updatePet
</code></pre>

### 重排目录中的页面

生成的标签页或标签组的顺序与 OpenAPI 中标签的顺序一致 `tags` array:

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags:
<strong>  - name: pet
</strong><strong>  - name: store
</strong><strong>  - name: user
</strong></code></pre>

### 将页面嵌套到组中

要构建多级导航，请在标签中使用 `x-parent` （或 `parent`）来定义层级。这适用于这两种页面结构：

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags:
  - name: everything
  - name: pet
<strong>    x-parent: everything
</strong>  - name: store
<strong>    x-parent: everything
</strong></code></pre>

上面的示例会创建如下所示的目录：

```
Everything
├── 宠物
└── 商店
```

如果 GitBook 生成了一个父页面且该页面没有描述，则会为其子页面显示基于卡片的布局。

### 自定义页面标题、图标和描述

你可以使用位于 `tags` 部分中的自定义扩展来增强生成的标签页和导航标签。所有 [Font Awesome 图标](https://fontawesome.com/search) 均通过 `x-page-icon`.

{% code title="openapi.yaml" %}

```yaml
tags:
  - name: pet
    # 目录和页面中显示的页面标题
    x-page-title: Pet
    # 目录和页面标题旁显示的图标
    x-page-icon: dog
    # 标题上方显示的描述
    x-page-description: 宠物真棒！
    # 页面内容
    description: 关于你的宠物的一切
```

{% endcode %}

### 使用 GitBook Blocks 构建丰富的描述

标签描述字段支持 GitBook Markdown，包括 [高级块](/docs/documentation/zh/creating-content/blocks.md) 如选项卡：

{% code title="openapi.yaml" %}

```yaml
---
tags:
  - name: pet
    description: |
      这里是宠物的详细信息。

      {% tabs %}
      {% tab title="Dog" %}
      这里是狗
      {% endtab %}

      {% tab title="Cat" %}
      这里是猫
      {% endtab %}

      {% tab title="Rabbit" %}
      这里是兔子
      {% endtab %}
      {% endtabs %}
```

{% endcode %}

### 高亮 schema

你可以使用 GitBook Markdown 在 GitBook 描述中高亮一个 schema。下面是一个示例，它高亮了“petstore”规范中的“Pet” schema：

{% code title="openapi.yaml" %}

```yaml
---
tags:
  - 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 文件中定义 webhooks，GitBook 会将它们与你的其他 API 操作一起渲染。有关跨 OpenAPI 文档的版本支持，请参见 [OpenAPI 兼容性](/docs/documentation/zh/api-references/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/api-references/guides/structuring-your-api-reference.md?ask=<question>&goal=<endgoal>
```

`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.