write-openapi

GitBook OpenAPI

GitBook 可将 OpenAPI 文档转换为交互式、可测试的 API 参考内容块。你只需提供一份规范（JSON 或 YAML 格式），它就会呈现端点、参数、架构、身份验证，以及页面内的请求运行器。大多数自定义都通过规范本身的 x-* 扩展完成，而非在 GitBook UI 中操作，因此这类任务的大部分工作就是正确编辑 OpenAPI YAML。

本技能涵盖完整流程：将规范导入 GitBook、生成参考页面、构建导航、让“Test it”运行器正常工作、控制操作和架构的显示方式，以及通过 CI/CD 自动更新。

如何与 GitBook 交互

本技能的大部分内容——编辑 OpenAPI YAML/JSON 本身——与传输方式无关。但将规范导入 GitBook，或生成/插入参考页面时，就需要与 GitBook 交互；而这有不止一种方式：GitBook MCP 服务和 REST API。请检查当前会话中实际可用的功能，并优先选择 MCP：如果已连接 GitBook MCP 工具，就用它们处理其支持的操作（发布/更新规范、生成参考页面），而不是直接调用 API。不要为此运行检测脚本——你已经知道自己可用的工具/MCP 连接；直接利用这些信息即可。

以下步骤按目标（“添加规范”“生成参考页面”）描述，而非绑定到某种传输方式，因此无论采用哪种方式都适用。如果已连接 GitBook MCP 工具，请直接调用；它们各自的架构会说明所需参数。如果改用 REST API，具体端点和请求正文见下文“添加或更新规范”。

• GitBook MCP — 提供完整的读写能力，涵盖下文所述的相同功能，并非功能更少的版本。如果尚未连接，且任务足够重要、值得进行设置（例如发布新规范、生成完整参考内容，而非一次性小调整），请提出设置建议：claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp（然后运行 /mcp 完成 OAuth 登录；或者追加 --header "Authorization: Bearer $GITBOOK_TOKEN"，跳过浏览器流程）。Codex 对应命令：codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp。注意：这与 GitBook 单独提供的只读“published docs”MCP 服务不同；后者只能访问已发布的内容。
• REST API（https://api.gitbook.com/v1）— 在未连接 MCP，或遇到 MCP 不支持的操作时使用。每个请求都需要在 bearer 标头中提供 GITBOOK_TOKEN。

同一个个人访问令牌（可从 https://app.gitbook.com/account/developer 获取）既可用作 bearer 令牌，也可用于这两种方式。MCP 还支持 OAuth，是比粘贴令牌更方便的替代方案。

如果需要令牌（使用 REST API，或在未使用 OAuth 的情况下使用 MCP），请在会话开始时检查是否已有令牌：

[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"

如果未设置 GITBOOK_TOKEN，请直接询问用户：

1. 告知他们需要 GitBook 个人访问令牌，并引导他们前往 https://app.gitbook.com/account/developer 创建令牌。
2. 请他们将令牌粘贴到对话中。随后立即将其导出为环境变量（export GITBOOK_TOKEN=<pasted value>），并且不要在回复中重复令牌。
3. 在确认环境中已存在令牌之前，不要进行任何 API 调用。

绝不要将令牌写入文件、在回复中回显令牌，或提交令牌。

GitBook CLI 的 gitbook openapi publish 命令（见下文“添加或更新规范”）与 API 和 MCP 一样，可调用底层的相同功能——它只是一个便捷封装，并非一套独立的功能；它使用相同的 GITBOOK_TOKEN 进行身份验证。

首先需要了解的关键事实

这些因素会影响几乎所有决策，因此在编辑任何内容之前，请先牢记。

• 支持的版本。 GitBook 接受 Swagger 2.0 和 OpenAPI 3.0 规范。某些功能需要更新的版本：webhook 需要 OpenAPI 3.1，官方的 parent 标签属性需要 OpenAPI 3.2+（在 3.0.x 和 3.1.x 中使用 x-parent）。在使用受版本限制的功能之前，务必先检查规范中的 openapi:/swagger: 版本。
• “Test it” 运行器由 Scalar 提供支持。 除非通过 GitBook 的代理路由，否则它会从读者的浏览器发送请求。
• 规范的来源是文件或 URL——这决定了更新方式，而不是你用来设置来源的传输方式（MCP、API、CLI 或 UI）。 URL 来源每 6 小时自动刷新一次；文件来源只有在重新上传或重新发布时才会更改。
• x-* 扩展有命名空间，可以安全地保留在共享规范中。 不理解特定扩展的工具会忽略它，因此为 GitBook 添加扩展的规范仍可在其他地方通过验证并正常运行。

你想做什么？

根据任务找到对应部分。更深入的参考资料有两个文件，位于此文件所在目录：

• 编辑或查找任何 x-* 扩展，并查看每个扩展的完整 YAML：阅读 references/extensions.md。
• 让交互式运行器端到端正常工作（身份验证方案、服务器、CORS、代理）：阅读 references/test-it-setup.md。

任务	前往
将规范添加到 GitBook，或更新规范	“添加或更新规范”
生成参考页面，或将单个端点/架构添加到页面	“插入 API 参考”
拆分、排序、嵌套页面，或为页面添加标题和图标	“构建参考结构”
让“Test it”正常工作、修复 CORS、配置身份验证	“配置 Test it 运行器” + references/test-it-setup.md
将端点标记为实验性、已弃用或隐藏	“管理操作生命周期”
查找扩展的准确名称/作用范围	“扩展速查表” + references/extensions.md
通过流水线自动发布规范	“使用 CI/CD 自动化”

添加或更新规范

在组织中添加规范之前，任何区块或页面都无法引用它。无论使用哪种传输方式，添加和更新本质上都是同一操作——根据上文“如何与 GitBook 交互”选择你可用的方式。无论使用哪种方式，都要预先为规范指定名称/slug：之后你需要用它来引用规范，也需要用它来区分多个规范。

GitBook MCP — 如果已连接，可直接使用其规范工具，从文件或 URL 创建或更新规范；其架构同时涵盖这两种来源类型。

REST API — 使用 URL 来源创建：

curl -s -X POST -H "Authorization: Bearer $GITBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "<spec-name>", "source": {"url": "<hosted-url>"}}' \
  https://api.gitbook.com/v1/orgs/$ORG_ID/openapi

或从文件创建：

curl -s -X POST -H "Authorization: Bearer $GITBOOK_TOKEN" \
  -F "slug=<spec-name>" \
  -F "file=@./openapi.yaml" \
  https://api.gitbook.com/v1/orgs/$ORG_ID/openapi

以同样的方式对 PATCH /v1/orgs/{orgId}/openapi/{specId} 执行操作，即可更新（替换）现有规范。

GitBook CLI — 对同一 API 调用的轻量封装，适用于脚本和流水线（同一命令可添加或更新；对 URL 运行时也会强制刷新）：

gitbook openapi publish --spec <spec-name> --organization <organization-id> <path-or-url>

流水线自动化请参阅“使用 CI/CD 自动化”。CLI 详情：https://gitbook.com/docs/developers/integrations/reference

GitBook 应用 UI — 在侧边栏中打开 OpenAPI 部分，点击 Add specification，为规范命名，然后选择上传文件或输入托管的 URL。更新方式取决于来源：URL 来源每 6 小时自动检查一次（点击 Check for updates 可立即拉取；在面包屑操作菜单中点击 Edit，可将 File 切换为 URL）；文件来源则需要点击 Update 上传新版本。

插入 API 参考

规范创建完成后，可以通过以下两种方式之一在文档中呈现它。

生成完整的页面集（推荐用于完整参考）。 在目标空间的目录中，点击底部的 Add new...，然后点击 OpenAPI Reference，选择规范并插入。GitBook 会为规范中的每个标签创建一个页面（参见“整理参考”），还可以选择创建一个列出所有架构的模型页面。规范更新时，这些页面也会随之更新。

将单个操作或架构插入现有页面。 按 /，搜索 OpenAPI，选择规范，点击 Continue，然后选择要嵌入的具体操作和／或架构。

块语法。 直接编写 GitBook markdown 时，OpenAPI 操作块如下所示（内部行重复了来源）：

{% openapi src="https://petstore3.swagger.io/api/v3/openapi.json" path="/pet" method="post" %}
https://petstore3.swagger.io/api/v3/openapi.json
{% endopenapi %}

若要在行内突出显示一个或多个架构（例如在标签描述中），请使用架构块：

{% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}
The Pet object
{% endopenapi-schemas %}

整理参考

GitBook 根据规范的 tags 构建导航，因此整理参考主要就是整理标签。此处提及的每个扩展的完整 YAML 都在 references/extensions.md 中。

• 将操作拆分到多个页面： 为操作指定相同的标签，每个标签都会成为独立页面。

  paths:
    /pet:
      put:
        tags:
          - pet
        summary: Update an existing pet.
        operationId: updatePet
  

• 排列页面顺序： 页面顺序与顶层 tags 数组中条目的顺序一致。

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

• 将页面嵌套到分组中： 使用 parent（OpenAPI 3.2+）或 x-parent（3.0.x/3.1.x）将标签指向其父标签。

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

  如果父页面没有 description，GitBook 会自动呈现以卡片为基础的布局，并链接到其子页面。

• 为每个页面添加标题、图标和描述，方法是使用标签级扩展。图标可使用任意 Font Awesome 名称（https://fontawesome.com/search）。

  tags:
    - name: pet
      x-page-title: Pet              # title in the table of contents and page header
      x-page-icon: dog               # icon in the ToC and next to the title
      x-page-description: Pets are amazing!   # shown just above the title
      description: Everything about your Pets # the page body
  

• 编写丰富的描述。 标签的 description 字段支持 GitBook markdown，包括 {% tabs %} 等高级块，因此页面简介可以远不止纯文本。

• 记录 Webhook（OpenAPI 3.1），方法是使用顶层 webhooks 字段，其结构与 paths 相同：

  openapi: 3.1.0
  webhooks:
    newPet:
      post:
        summary: New pet event
        requestBody:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        responses:
          "200":
            description: Received successfully
  

配置 Test it 运行器

交互式运行器的效果取决于规范对 API 的描述。运行器会向 servers 数组中的 URL 发起请求，且只能使用规范在 components.securitySchemes 下声明的身份验证方式。对于任何较复杂的情况（Bearer/JWT、API 密钥、OAuth2、多个或模板化的服务 URL、按操作覆盖设置），请参阅 references/test-it-setup.md，其中提供了适用于各种模式的 YAML，可直接复制粘贴。

你经常需要做出以下两个决定：

• “为什么我的规范无法加载？”／“为什么 Test it 会失败？”（URL 规范）。 这几乎总是 CORS 问题。通过 URL 添加的规范要求 API 允许来自文档源站（例如 https://your-site.gitbook.io 或你的自定义域名）的跨源 GET 请求。不需要凭据的公开端点可以返回 Access-Control-Allow-Origin: *。
• API 无法启用 CORS？ 使用 x-enable-proxy: true 通过 GitBook 的代理转发请求（可在根级别为整个规范设置，也可针对单个操作设置；操作级设置优先）。代理会转发所有 HTTP 方法、标头、Cookie 和请求正文，但只会转发到 servers 中列出的 URL，因此请确保要测试的每个基础 URL 都包含在该数组中。详情请参阅 references/test-it-setup.md。

若要从某个端点（或整个规范）中移除运行器，请设置 x-hideTryItPanel: true。

管理操作生命周期

当端点尚未达到生产就绪状态或正在逐步淘汰时，通常会用到这些设置。除非另有说明，以下设置均针对操作级别。

• 尚不稳定： x-stability: experimental（也可以是 alpha 或 beta）。
• 已弃用： deprecated: true。已弃用的端点会在发布的网站上显示弃用警告。
• 设置弃用截止日期： 添加 x-deprecated-sunset: 2030-12-05（ISO 8601 格式，YYYY-MM-DD）。
• 完全隐藏端点： x-internal: true（或别名 x-gitbook-ignore: true）。
• 隐藏单个响应示例： 在该响应对象上设置 x-hideSample: true（例如，在 responses.200 下）。

paths:
  /pet:
    put:
      operationId: updatePet
      x-stability: experimental
      deprecated: true
      x-deprecated-sunset: 2030-12-05

扩展速查表

一览所有 GitBook 支持的扩展。要查看任意一行对应的完整 YAML 示例，请打开 references/extensions.md。

扩展	用途	位置
x-page-title / x-displayName	显示标签名称（导航栏 + 页面标题）	标签
x-page-description	显示在页面标题上方的简短描述	标签
x-page-icon	页面的 Font Awesome 图标	标签
parent / x-parent	将标签嵌套在父级标签下（parent = 3.2+，x-parent = 3.0.x/3.1.x）	标签
x-hideTryItPanel	显示或隐藏“测试”运行器	根级或操作级
x-expandAllResponses	默认展开所有响应部分	根级或操作级
x-expandAllModelSections	默认展开所有模型/架构部分	根级或操作级
x-enable-proxy	通过 GitBook 代理转发“测试”请求	根级或操作级（操作级优先）
x-codeSamples	提供自定义代码示例（lang、label、source）	操作
x-enumDescriptions	为 enum 的每个值提供描述，并以表格形式呈现	架构
x-internal / x-gitbook-ignore	从参考文档中隐藏端点	操作
x-stability	标记为 experimental、alpha 或 beta	操作
deprecated	将操作标记为已弃用	操作
x-deprecated-sunset	已弃用操作的截止日期（YYYY-MM-DD）	操作
x-hideSample	隐藏单个响应示例	响应对象
x-gitbook-prefix	自定义身份验证前缀（例如 Token）；不允许用于 http 方案	安全方案
x-gitbook-token-placeholder	在运行器中显示的默认令牌占位符	安全方案

以下两个显示扩展值得特别关注，因为它们可设置根级默认值，而操作可以选择不采用这些默认值：

openapi: '3.0'
x-expandAllResponses: true        # default for every operation
x-expandAllModelSections: true
paths:
  /pets:
    get:
      x-expandAllResponses: false # opt this one out

自定义代码示例会替换 GitBook 自动生成的代码片段，并支持多种语言：

paths:
  /users:
    get:
      summary: Retrieve users
      x-codeSamples:
        - lang: JavaScript
          label: Node SDK
          source: |
            import { createAPIClient } from 'my-api-sdk';
            const client = createAPIClient({ apiKey: 'my-api-key' });
            client.users.list().then(console.log);
        - lang: cURL
          label: CLI
          source: |
            curl -L -H 'Authorization: Bearer <token>' \
              'https://api.example.com/v1/users'

使用 CI/CD 自动化

使用 CLI 从任意流水线发布规范。将 GITBOOK_TOKEN 设置为密钥，然后对文件（在构建期间生成）或 URL 运行 openapi publish（在发布后强制刷新）。

export GITBOOK_TOKEN=<api-token>
gitbook openapi publish \
  --spec <spec-name> \
  --organization <organization-id> \
  example.openapi.yaml

GitHub Actions 示例：在 main 上的规范发生更改时触发：

name: Publish OpenAPI to GitBook
on:
  push:
    branches: ["main"]
    paths: ["**/*.yaml", "**/*.yml", "**/*.json"]
  workflow_dispatch:
jobs:
  publish:
    runs-on: ubuntu-latest
    env:
      GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
      GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}
      GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}
    steps:
      - uses: actions/checkout@v4
      - name: Publish spec to GitBook
        run: |
          npx -y @gitbook/cli@latest openapi publish \
            --spec "$GITBOOK_SPEC_NAME" \
            --organization "$GITBOOK_ORGANIZATION_ID" \
            <path_to_spec>