> 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 参考结构

了解如何使用图标和描述在多个页面中组织你的 API 参考

GitBook 不仅仅是渲染您的 OpenAPI 规范。它还允许您自定义 API 参考文档，以获得更好的清晰度、导航和品牌展示。

要在 **每个标签一个页面** 以及 **每个操作一个页面**之间进行选择，请参见 [OpenAPI 布局](/docs/documentation/zh/chuang-jian-nei-rong/openapi/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>        - 宠物
</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: 宠物
</strong><strong>  - name: 商店
</strong><strong>  - name: user
</strong></code></pre>

### 嵌套页面到组中

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

<pre class="language-yaml" data-title="openapi.yaml"><code class="lang-yaml">tags:
  - name: 全部
  - name: 宠物
<strong>    x-parent: 全部
</strong>  - name: 商店
<strong>    x-parent: 全部
</strong></code></pre>

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

```
全部
├── 宠物
└── 商店
```

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

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

您可以在 `tags` 部分。所有 [Font Awesome 图标](https://fontawesome.com/search) 可通过 `x-page-icon`.

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

```yaml
tags:
  - name: 宠物
    # 目录和页面中显示的页面标题
    x-page-title: 宠物
    # 目录中显示以及页面标题旁显示的图标
    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
---
tags:
  - name: 宠物
    description: |
      这里是宠物的详细信息。

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

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

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

{% endcode %}

### 高亮 schema

您可以通过使用 GitBook Markdown 在 GitBook 描述中高亮一个 schema。以下是一个示例，用于高亮 “petstore” 规范中的 “Pet” schema：

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

```yaml
---
tags:
  - name: 宠物
      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/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=<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.