构建您的 API 参考结构
了解如何跨多个页面使用图标和描述来组织 API 参考
GitBook 不仅仅是渲染你的 OpenAPI 规范。它还允许你自定义 API 参考文档以提高清晰度、导航性和品牌统一性。
将操作拆分到多个页面
为了保持文档有序，GitBook 可以将你的 API 操作拆分到单独的页面。每个页面由 OpenAPI 规范中的一个标签生成。要将操作分组到一个页面，请为每个操作分配相同的标签：
paths:
/pet:
put:
tags:
- pet
summary: 更新已存在的宠物。
description: 通过 Id 更新已存在的宠物。
operationId: updatePet在目录中重新排序页面
GitBook 中页面的顺序与 OpenAPI tags 数组中标签的顺序一致：
tags:
- name: pet
- name: store
- name: user将页面嵌套到分组中
要构建多级导航，请在 x-parent （或 parent）标签中使用以定义层级：
上述示例将创建如下所示的目录：
如果某个页面没有描述，GitBook 将自动为其子页面显示基于卡片的布局。
自定义页面标题、图标和描述
你可以在标签部分使用自定义扩展为页面增强标题、图标和描述。所有 Font Awesome 图标 都通过 x-page-icon.
使用 GitBook Blocks 构建丰富的描述
标签描述字段支持 GitBook markdown，包括 高级区块 比如选项卡：
突出显示模式（schemas）
你可以在 GitBook 描述中使用 GitBook markdown 来突出显示一个模式。下面是一个示例，突出显示来自 “petstore” 规范的 “Pet” 模式：
为 webhook 端点编写文档
在使用 OpenAPI 3.1 时，GitBook 还支持为 webhook 端点编写文档。
你可以在 OpenAPI 文件中直接使用 webhooks 字段来定义你的 webhooks，该字段的工作方式类似于 paths 用于常规 API 端点：
最后更新于
这有帮助吗？