用途：在 GitBook 中把 OpenAPI/Swagger 规范转成可交互、可测试的 API 参考文档，并负责编写、配置、组织与排查。
主要能力：支持 Swagger 2.0 与 OpenAPI 3.0；webhooks 需 3.1，parent 标签属性需 3.2+（3.0.x/3.1.x 用 x-parent）。可通过上传文件、托管 URL 或 GitBook CLI 添加规范；URL 源每 6 小时自动刷新，文件源需重新上传。可生成整套参考页（按 tag 分页，可选 models 页），也可在页面内嵌入单个 operation 或 schema。导航由 tag 决定：同 tag 归为一页，页面顺序按顶层 tags 数组，可用 parent/x-parent 嵌套，用 x-page-title、x-page-icon、x-page-description 定制标题、图标与描述。Test it 运行器由 Scalar 驱动，依赖 servers 与 components.securitySchemes；URL 源常见失败原因是 CORS，可用 x-enable-proxy 走 GitBook 代理，用 x-hideTryItPanel 隐藏运行器。生命周期可用 x-stability、deprecated、x-deprecated-sunset、x-internal/x-gitbook-ignore、x-hideSample 控制。x-* 扩展带命名空间，不影响其他工具校验。
使用方式：CLI 发布或更新（同一命令）：gitbook openapi publish --spec <spec-name> --organization <organization-id> <path-or-url>，需设置 GITBOOK_TOKEN。CI/CD 中可用 npx -y @gitbook/cli@latest openapi publish 配合 GitHub Actions。
适用场景：维护 API 参考文档、从流水线自动发布规范、排查 Test it 与 CORS 问题。
限制：代理仅转发到 servers 中列出的 URL；部分特性受 OpenAPI 版本限制；资料未提供收费与价格信息。