# 构建你的 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: Pet
    # 在目录中以及页面标题旁显示的图标
    x-page-icon: dog
    # 显示在标题上方的描述
    x-page-description: Pets are amazing!
    # 页面内容
    description: 关于你的宠物的一切
```

{% endcode %}

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

标签描述字段支持 GitBook markdown，包括 [高级块](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/creating-content/blocks) 例如标签页：

{% 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` 字段来定义你的 webhook，其工作方式与常规 API 端点的 `paths` 类似：

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

```yaml
---
openapi: 3.1.0 # 自 OpenAPI 3.1 起可用 webhook

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

{% endcode %}