用途:在 GitBook 中把 OpenAPI/Swagger 规格转成可交互、可测试的 API 参考文档,并处理配置、结构组织与故障排查。
主要能力:支持添加规格(上传文件、托管 URL、CLI 发布);生成整组参考页或把单个端点/模型嵌入已有页面;按 tag 拆分、排序、嵌套页面并设置标题、图标、描述;配置 Test it 运行器(由 Scalar 驱动,处理认证、服务器与 CORS,可用 x-enable-proxy 走 GitBook 代理);用 x-* 扩展控制显示、隐藏端点、标记实验/废弃状态;提供 x-codeSamples、x-enumDescriptions 等;可从 CI/CD 自动发布。
必要用法:规格须先存在于组织内。GitBook 接受 Swagger 2.0 与 OpenAPI 3.0,webhooks 需 3.1,parent 需 3.2+(低版本用 x-parent)。URL 源每 6 小时自动刷新,文件源需手动更新。CLI 发布命令:gitbook openapi publish --spec <spec-name> --organization <organization-id> <path-or-url>,通过 GITBOOK_TOKEN 环境变量认证。嵌入块语法:{% openapi src="..." path="..." method="..." %}。
适用场景:为 API 编写面向开发者的参考文档,或将规格更新自动同步到文档站点。限制:大部分定制在规格内通过 x-* 完成,而非 GitBook UI;URL 源与运行器受 CORS 影响,需 API 允许跨域或启用代理;未提供收费与价格信息。