在 GitBook 中编写、接入、配置和排错…

当任务涉及 GitBook OpenAPI/Swagger spec、`{% openapi %}` block、API reference 页面、Test it runner 或 CI/CD 自动更新时使用。

适用场景

解决思路

1. 编辑 OpenAPI YAML/JSON 本身与传输方式无关；只有把 spec 接入 GitBook、生成/插入参考页时才涉及 GitBook 通道。先检查当前会话可用工具，优先 GitBook MCP；若已连接 MCP，用它发布/更新 spec、生成参考页，不要直接调 REST API；不要跑探测脚本，直接根据已知可用工具/MCP 连接判断。
2. 若未连接 GitBook MCP 且任务较大（发布新 spec、生成完整参考页），可建议安装：Claude 用 `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 不同的服务器。
3. REST API 作为 MCP 未连接或未覆盖时的后备：基址 `https://api.gitbook.com/v1`，每个请求加 bearer header，使用 `GITBOOK_TOKEN`。
4. 同一个 personal access token（从 https://app.gitbook.com/account/developer 创建）可用于 MCP 和 REST API 的 bearer token；MCP 还支持 OAuth，作为免粘贴 token 的替代方式。
5. 若需要 token（REST API 路径，或 MCP 不用 OAuth），会话开始检查：`[ -n "$GITBOOK_TOKEN" ] && echo "Token found" || echo "GITBOOK_TOKEN is not set"`。
6. 若 `GITBOOK_TOKEN` 未设置，直接询问用户：1) 告知需要 GitBook personal access token，并引导到 https://app.gitbook.com/account/developer 创建；2) 请用户把 token 粘贴到对话中，立即 `export GITBOOK_TOKEN=<pasted value>` 作为环境变量，不要在回复里复述；3) 在确认环境变量存在前，不要进行任何 API 调用。
7. token 安全：永远不要把 token 写入文件、在响应中 echo 出来、或提交到版本库。
8. CLI 的 `gitbook openapi publish` 与 API/MCP 底层能力相同，是便捷封装，并使用相同 `GITBOOK_TOKEN` 认证。
9. 使用版本门控功能前，先检查 spec 的 `openapi:`/`swagger:` 版本：GitBook 接受 Swagger 2.0 和 OpenAPI 3.0；webhooks 需要 OpenAPI 3.1；官方 `parent` tag 属性需要 OpenAPI 3.2+，在 3.0.x/3.1.x 用 `x-parent`。
10. 配置 Test it 时，按 Scalar 行为处理：它由 Scalar 驱动；除路由到 GitBook proxy 外，请求从读者浏览器发出。
11. 更新 spec 前先确认来源是 file 还是 URL：这决定更新方式，而不是用哪种 transport（MCP、API、CLI 或 UI）设置；URL 来源每 6 小时自动刷新；file 来源只在重新上传或重新发布时变化。
12. 在共享 spec 中可保留 `x-*` 扩展：它们有命名空间，不理解某扩展的工具会忽略它，因此为 GitBook 插桩的 spec 仍可在别处校验和工作。
13. 需要编辑或查询任何 `x-*` 扩展及完整 YAML 时，读 `references/extensions.md`；需要端到端让交互式 runner 工作（认证方案、servers、CORS、proxy）时，读 `references/test-it-setup.md`。
14. 按任务查表：把 spec 接入或更新 GitBook 见 Add or update a specification；生成参考页或插入单个 endpoint/schema 见 Insert an API reference；拆分/排序/嵌套/标题/图标页面见 Structure the reference；让 Test it 工作、修复 CORS、配置认证见 Configure the Test it runner + `references/test-it-setup.md`；标记 endpoint experimental/deprecated/hidden 见 Manage operation lifecycle；查扩展名称/范围见 Extensions cheat-sheet + `references/extensions.md`；从 pipeline 自动发布见 Automate with CI/CD。
15. 添加或更新 spec：spec 必须先存在于 organization 中，block 或 page 才能引用；添加和更新在所有 transport 上是同一底层操作，按上面选择可用通道；一开始就给 spec 一个 name/slug，用于后续引用和区分多个 spec。
16. 使用 GitBook MCP：若已连接，直接调用其 spec 工具从 file 或 URL 创建/更新 spec；工具 schema 覆盖两种来源。
17. 使用 REST API 从 URL 创建 spec：`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`。
18. 使用 REST API 从 file 创建 spec：`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`。
19. 更新（替换）已有 spec：同样方式请求 `PATCH /v1/orgs/{orgId}/openapi/{specId}`。
20. 使用 GitBook CLI 添加或更新：`gitbook openapi publish --spec <spec-name> --organization <organization-id> <path-or-url>`；同一命令可添加或更新，对 URL 运行还会强制刷新。CLI 细节见 https://gitbook.com/docs/developers/integrations/reference。
21. 使用 GitBook app UI：侧边栏打开 **OpenAPI** 区域，点击 **Add specification**，命名，然后选择上传 file 或输入 hosted URL。更新取决于来源：URL 来源每 6 小时自动检查（点击 **Check for updates** 可立即拉取；通过面包屑操作菜单的 **Edit** 把 File 切为 URL）；file 来源需要点击 **Update** 上传新版本。
22. 插入 API reference：spec 存在后，用两种方式之一呈现。
23. 生成整套页面（完整 reference 推荐）：在目标 space 的 table of contents 点击底部 **Add new...**，再点 **OpenAPI Reference**，选择 spec 并插入。GitBook 会按 spec 中的 tag 每 tag 创建一页，并可选创建一个 models 页列出所有 schema；这些页面会随 spec 更新而更新。
24. 把单个 operation 或 schema 插入已有页面：按 `/`，搜索 **OpenAPI**，选择 spec，点 **Continue**，然后选择要嵌入的具体 operations 和/或 schemas。
25. 直接写 GitBook markdown 时，OpenAPI operation block 语法为：`{% openapi src="https://petstore3.swagger.io/api/v3/openapi.json" path="/pet" method="post" %}`，下一行重复来源 `https://petstore3.swagger.io/api/v3/openapi.json`，然后 `{% endopenapi %}`。
26. 内联高亮一个或多个 schema（例如在 tag description 内）用 schemas block：`{% openapi-schemas spec="petstore" schemas="Pet" grouped="false" %}`，正文写 `The Pet object`，然后 `{% endopenapi-schemas %}`。
27. 组织 reference：GitBook 从 spec 的 `tags` 构建导航，因此组织 reference 主要是组织 tags。
28. 拆分 operations 到不同页面：给 operations 相同 tag，每个 tag 变成自己的页面。示例 YAML：`paths: /pet: put: tags: [pet] summary: Update an existing pet. operationId: updatePet`。
29. 页面排序：页面顺序遵循顶层 `tags` 数组中的条目顺序。示例：`tags: - name: pet - name: store - name: user`。
30. 嵌套页面成组：用 `parent`（OpenAPI 3.2+）或 `x-parent`（3.0.x/3.1.x）把 tag 指向父 tag。示例：`tags: - name: everything - name: pet x-parent: everything - name: store x-parent: everything`。如果父页面没有 `description`，GitBook 会自动渲染卡片式布局链接子页面。
31. 为每个页面加标题、图标和描述：用 tag 级扩展；图标接受任意 Font Awesome 名称（https://fontawesome.com/search）。示例：`tags: - name: pet x-page-title: Pet x-page-icon: dog x-page-description: Pets are amazing! description: Everything about your Pets`。
32. 写丰富描述：tag `description` 字段接受 GitBook markdown，包括 `{% tabs %}` 等高级 block，因此页面介绍可以远不止纯文本。
33. 记录 webhooks（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`。
34. 配置 Test it runner：runner 的效果取决于 spec 描述；它请求 `servers` 数组中的 URL，只能展示 `components.securitySchemes` 中声明的 auth。对非简单场景（Bearer/JWT、API key、OAuth2、多个或模板化 server URL、按 operation 覆盖），读 `references/test-it-setup.md` 获取可复制 YAML。
35. 修复 URL spec 的“为什么 spec 未加载/Test it 失败”：几乎总是 CORS。URL 添加的 spec 要求 API 允许来自 docs origin（例如 `https://your-site.gitbook.io` 或自定义域名）的跨域 GET。公开且无需凭据的 endpoint 可以返回 `Access-Control-Allow-Origin: *`。
36. API 无法开启 CORS 时：用 `x-enable-proxy: true` 把请求路由到 GitBook proxy（放在 root 作用于整个 spec，或放在单个 operation；operation 值优先）。proxy 会转发所有 HTTP methods、headers、cookies 和 bodies，但只转发到 `servers` 中列出的 URL，因此确保要测试的每个 base URL 都在该数组中。详情见 `references/test-it-setup.md`。
37. 要从 endpoint 或整个 spec 移除 runner：设置 `x-hideTryItPanel: true`。
38. 管理 operation 生命周期（endpoint 未生产就绪或正在淘汰时常用；以下均为 operation 级，除非标注）。
39. 未稳定：`x-stability: experimental`（也可 `alpha` 或 `beta`）。
40. 已废弃：`deprecated: true`；废弃 endpoint 会在发布站点显示警告。
41. 带结束日期的废弃：添加 `x-deprecated-sunset: 2030-12-05`（ISO 8601，`YYYY-MM-DD`）。
42. 完全隐藏 endpoint：`x-internal: true`（或别名 `x-gitbook-ignore: true`）。
43. 隐藏单个响应示例：在该 response 对象上设置 `x-hideSample: true`（例如 `responses.200` 下）。
44. 生命周期示例 YAML：`paths: /pet: put: operationId: updatePet x-stability: experimental deprecated: true x-deprecated-sunset: 2030-12-05`。
45. 扩展速查——`x-page-title` / `x-displayName`：tag 的显示名称（导航 + 页面标题）；位置：tag。
46. `x-page-description`：显示在页面标题上方的短描述；位置：tag。
47. `x-page-icon`：页面的 Font Awesome 图标；位置：tag。
48. `parent` / `x-parent`：把 tag 嵌套到父 tag 下（`parent` = 3.2+，`x-parent` = 3.0.x/3.1.x）；位置：tag。
49. `x-hideTryItPanel`：显示或隐藏 Test it runner；位置：root 或 operation。
50. `x-expandAllResponses`：默认展开所有 response 区域；位置：root 或 operation。
51. `x-expandAllModelSections`：默认展开所有 model/schema 区域；位置：root 或 operation。
52. `x-enable-proxy`：把 Test it 请求路由到 GitBook proxy；位置：root 或 operation（operation 优先）。
53. `x-codeSamples`：提供自定义代码示例（`lang`、`label`、`source`）；位置：operation。
54. `x-enumDescriptions`：为 `enum` 的每个值提供描述，渲染为表格；位置：schema。
55. `x-internal` / `x-gitbook-ignore`：从 reference 中隐藏 endpoint；位置：operation。
56. `x-stability`：标记 `experimental`、`alpha` 或 `beta`；位置：operation。
57. `deprecated`：标记 operation 已废弃；位置：operation。
58. `x-deprecated-sunset`：废弃 operation 的 sunset 日期（`YYYY-MM-DD`）；位置：operation。
59. `x-hideSample`：隐藏单个 response 示例；位置：response object。
60. `x-gitbook-prefix`：自定义 auth 前缀（例如 `Token`）；不允许用在 `http` schemes 上；位置：security scheme。
61. `x-gitbook-token-placeholder`：runner 中显示的默认 token 占位符；位置：security scheme。
62. 显示类扩展根默认/operation opt-out 示例：`openapi: '3.0' x-expandAllResponses: true x-expandAllModelSections: true paths: /pets: get: x-expandAllResponses: false`。
63. 自定义代码示例会替换 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'`。
64. CI/CD 自动化：用 CLI 从任意 pipeline 发布 spec。把 `GITBOOK_TOKEN` 设为 secret，然后对 file（构建期间生成）或 URL（发布后强制刷新）运行 `openapi publish`。
65. CI/CD bash 示例：`export GITBOOK_TOKEN=<api-token>`，然后 `gitbook openapi publish --spec <spec-name> --organization <organization-id> example.openapi.yaml`。
66. GitHub Actions 示例：在 `on.push.branches: ["main"]` 且 `paths: ["**/*.yaml", "**/*.yml", "**/*.json"]` 以及 `workflow_dispatch` 触发；job `publish` 在 `ubuntu-latest`；env `GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}`、`GITBOOK_SPEC_NAME: ${{ vars.GITBOOK_SPEC_NAME }}`、`GITBOOK_ORGANIZATION_ID: ${{ vars.GITBOOK_ORGANIZATION_ID }}`；步骤 `actions/checkout@v4`，然后 `npx -y @gitbook/cli@latest openapi publish --spec "$GITBOOK_SPEC_NAME" --organization "$GITBOOK_ORGANIZATION_ID" <path_to_spec>`。

适用边界 · 注意事项

• 不适用于非 GitBook 的 OpenAPI/Swagger 文档渲染、测试或发布场景。
• 未连接 GitBook MCP 且无法提供 `GITBOOK_TOKEN`/OAuth、或无权创建 GitBook spec 时，不能执行接入与发布步骤。
• 若不需要 GitBook 的 `x-*` 扩展、Test it runner 或 CI/CD 自动发布，不要仅为 GitBook 改造共享 spec。