构建您的 API 参考结构

了解如何使用图标和说明将 API 参考分布在多页中进行结构化。

GitBook 不仅仅呈现你的 OpenAPI 规范。它还允许你自定义 API 参考，以获得更清晰的说明、更好的导航和品牌展示。

将操作拆分到多个页面

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

openapi.yaml

paths:
  /pet:
    put:
      tags:
        - pet
      summary: 更新现有宠物。
      description: 通过 Id 更新现有宠物。
      operationId: updatePet

在目录中重新排序页面

GitBook 中页面的顺序与 OpenAPI tags 数组中标签的顺序相匹配：

openapi.yaml

tags:
  - name: pet
  - name: store
  - name: user

将页面嵌套到分组中

要构建多级导航，请在标签中使用 x-parent （或 parent）来定义层级：

openapi.yaml

tags:
  - name: everything
  - name: pet
    x-parent: everything
  - name: store
    x-parent: everything

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

Everything
├── Pet
└── Store

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

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

你可以在标签部分使用自定义扩展为页面添加标题、图标和描述。所有 Font Awesome 图标 都通过以下方式支持： x-page-icon.

openapi.yaml

tags:
  - name: pet
    # 在目录和页面中显示的页面标题
    -x-page-title: Pet
    # 在目录中显示并位于页面标题旁的图标
    -x-page-icon: dog
    # 显示在标题上方的描述
    -x-page-description: Pets are amazing!
    # 页面内容
    description: 关于你的宠物的一切

使用 GitBook Blocks 构建丰富的描述

标签描述字段支持 GitBook Markdown，包括 高级区块 如选项卡：

openapi.yaml

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

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

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

      {% tab title="Rabbit" %}
      这里是兔子的内容
      {% endtab %}
      {% endtabs %}

突出显示模式（schemas）

你可以通过使用 GitBook Markdown 在 GitBook 描述中突出显示一个模式。下面是一个示例，突出显示来自 “petstore” 规范的 “Pet” 模式：

openapi.yaml

---
tags:
  - name: pet
      description: |
          {% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
              Pet 对象
          {% endopenapi-schemas %}