# 组织你的 API 参考

GitBook 不仅仅是渲染你的 OpenAPI 规范。它还让你自定义 API 参考文档，以提升清晰度、导航体验和品牌形象。

### 将操作拆分到多个页面

为了保持文档有条理，GitBook 可以将你的 API 操作拆分到独立的页面中。每个页面都由 OpenAPI 规范中的一个标签生成。要将操作分组到某个页面，请为每个操作分配相同的标签：

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

### 重新排序目录中的页面

GitBook 中页面的顺序与 OpenAPI tags 数组中的标签顺序一致：

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

上面的示例会创建一个看起来像这样的目录：

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

如果某个页面没有描述，GitBook 会自动为其子页面显示基于卡片的布局。

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

你可以使用 tags 部分中的自定义扩展来增强页面的标题、图标和描述。所有 [Font Awesome 图标](https://fontawesome.com/search) 都支持通过 `x-page-icon`.

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

```yaml
tags:
  - name: pet
    # 显示在目录和页面中的页面标题
    x-page-title: 宠物
    # 显示在目录中以及页面标题旁边的图标
    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 端点编写文档

在使用 OpenAPI 3.1 时，GitBook 也支持为 webhook 端点编写文档。

你可以在 OpenAPI 文件中直接使用 `webhooks` 字段来定义你的 webhooks，它的工作方式与常规 API 端点的 `paths` 类似：

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

```yaml
---
openapi: 3.1.0 # 从 OpenAPI 3.1 开始支持 Webhooks

webhooks:
  newPet:
    post:
      summary: 新宠物事件
      description: 系统中新宠物的信息
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: 返回 200 状态以表示数据已成功接收
```

{% endcode %}


---

# Agent Instructions: 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:

```
GET https://gitbook.com/docs/documentation/zh/api-references/guides/structuring-your-api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.