产品手册与 API 文档对照清单:OpenAPI 规格、交互式试调与同站发布

API 文档,是把 OpenAPI 或 Swagger 规格渲染成可查阅、可试调的接口参考,并与概念手册发布在同一套文档站里。它不等于只把 YAML 放进仓库,也不等于另搭一个与手册脱节的门户。本文对照 GitBook、Document360、ReadMe 与 Mintlify 给出验收清单。

浏览 10 巴克励步
产品手册与 API 文档对照清单:OpenAPI 规格、交互式试调与同站发布

导语:先分清「一份接口规格」和「一本给开发者用的手册」

API 文档,是把机器可读的接口规格——通常是 OpenAPI Specification(早期以 Swagger 为名)——渲染成开发者可以查阅参数、复制示例、并在页面上试调的接口参考,同时把认证说明、错误处理和集成指南等概念性产品手册放在同一套文档站里。它要回答的不是「仓库里有没有一份 YAML」,而是:规格变更之后参考页会不会跟上、读者能不能在文档里安全地发出测试请求,以及概念页和参考页是不是同一份已发布的知识资产。
四种常见做法不能写进同一格。第一种,只把 OpenAPI 文件提交到代码仓库,开发者要自行用本地工具打开。第二种,用独立的参考页生成器另搭一个开发者门户,和产品手册不在同一个站点、也不共用同一套发布与权限。第三种,在 Wiki 里手写每一个端点,规格一改,页面立刻过期。第四种,才是本文要验收的:规格是源,参考页由规格生成,概念手册与参考页同站发布,并且能按版本、权限和同步方式写进运行手册。
本文对照 GitBook 的 OpenAPI 文档能力、Document360 的 API 文档入门说明、ReadMe 的 OpenAPI 支持说明,以及 Mintlify 的 OpenAPI 配置文档。重点不是功能名谁更响,而是规格版本、同步方式、试调边界和同站发布能不能写进验收清单。

为什么现在要单独验收这条发布面

最近给产品手册做选型时,文档即代码与可发布企业 Wiki、多版本与多语言,以及 llms.txt / GEO,往往已经各自有对照清单。缺的是「接口规格如何变成和手册同一站的参考页」。开发者真正卡住的地方,经常是某个端点的参数、鉴权或错误码,而不是产品概述;如果参考页和概念页分属两套站点,或参考页仍靠手写,手册写对了,集成仍可能对着过期的路径。
2025 年 9 月,OpenAPI Initiative 发布了 OpenAPI Specification 3.2;2026 年 9 月 10 日,又发布了补丁版本 3.2.1,主要是对编码、style/explode 组合和路径匹配等说明的澄清,并不引入新的重大特性。3.2 本身增加了 QUERY 方法、更细的 querystring 建模、OAuth 2.0 Device Authorization Flow,以及对 Server-Sent Events、JSON Lines 等流式响应的描述。与此同时,各家文档站对规格版本的支持并不齐:Document360 的 API 基础说明 和入门文档把 OpenAPI 3.2 到 2.0 以及 Postman Collection 都列为可导入格式;Mintlify 写明支持 OpenAPI 3.0、3.1 和 3.2,Swagger 2.0 需先转换成 OpenAPI 3;GitBook 公开列出的是 Swagger 2.0、OpenAPI 3.0 与 3.1(含 webhooks);ReadMe 的兼容说明则是 OpenAPI 3.0.x/3.1、Swagger 2.0 和 Postman Collection。立项时不能只问「支不支持 OpenAPI」,而要问:你正在使用的规格版本,能不能被完整渲染。
另一条并行变化,是接口文档同时要给人和编码代理读。GitBook 把 OpenAPI 与配套指南写成 可被人和代理理解的产品知识,并提到可通过 MCP 和 llms.txt 对外提供;ReadMe 写明同一份规格也驱动项目的 MCP 服务器,供用户的 AI 工具列出端点、读取 schema 并发起调用;Mintlify 则把 API playground 与 MCP server 写进平台能力。这和已经写过的 Docs AI 可见性、MCP 接入 是同一条验收链上的不同面:先有一份已发布、版本正确的参考页,再谈它如何被检索或被代理调用。

四个容易混在一起的词

在短名单上把下面四个词拆开写。混用它们,最后往往买到「能导入 YAML」,却买不到「手册和参考页在同一个已发布站点里保持同步」。
概念 它真正回答的问题 典型落地方式
接口规格(OpenAPI / Swagger) 接口的机器可读描述是什么、版本是哪一个 JSON 或 YAML 文件,有时也包括 Postman Collection
API 参考 规格如何变成可读的端点页 由规格生成路径、参数、请求和响应示例
交互式试调 读者能否在文档页上发出真实请求并看到响应 Try It、API Explorer / playground;GitBook 的试调由 Scalar 驱动
概念手册 / 指南 如何认证、处理错误、完成一个完整集成 手写的教程与说明,应与参考页同站、同版本发布
一个可操作的判断句是:规格是源,参考页是生成物,试调是参考页上的操作面,概念手册是讲清楚「为什么这样调用」的说明。四行对不齐,文档站看起来完整,集成时仍会分叉。

先看对照表,再进入各家细节

验收项 GitBook Document360 ReadMe Mintlify
公开写明的规格版本 Swagger 2.0、OpenAPI 3.0、OpenAPI 3.1(含 webhooks) OpenAPI 3.2、3.1(含 webhooks)、3.0、2.0,以及 Postman Collection OpenAPI 3.0.x/3.1、Swagger 2.0,以及 Postman Collection v2.0/v2.1 OpenAPI 3.0、3.1、3.2;Swagger 2.0 需先转换成 OpenAPI 3
导入与同步 以文件或 URL 导入,规格变更后参考可自动更新;按 URL 加载时需允许文档站跨域 GET 本地或网盘上传、URL 导入,以及用 CLI 接入 CI/CD;URL 来源可手动再同步 上传或导入托管的 OpenAPI;可另加 Markdown,且在 operationId 不变时,再同步后仍保留 规格放进文档仓库或使用公开 HTTPS URL;规格变更后页面随之更新
交互式试调 页面内 “test it”,由 Scalar 驱动,不必离开文档 知识库站点上的 Try It! 控制台;webhook 页不提供 Try It! API Reference 可在文档内发起已认证的 API 请求,并提供可运行代码示例 每个端点页带 playground,可发真实请求,含图片、音视频和流式响应
与概念手册同站 可用站点分区把 API 参考与指南、教程、产品文档放在同一站点 API 文档是独立工作区,但参考页可发布到同一知识库站点 开发者中心同时容纳指南和由规格生成的 API Reference 可在导航中把 OpenAPI 参考做成单独的标签页,并与其他页面组合
规格与试调的访问边界 受保护站点可另配认证访问;按 URL 引入规格时要单独配置 CORS 付费方案提供 API 文档;Try It! 的 OAuth 需配置回调地址 同一份规格也可驱动 MCP;补充说明绑定在 operationId 上 未要求登录的站点会按路径提供仓库里的 JSON/YAML;从 URL 拉取规格时构建过程不带凭证
如果优先级是「把一份规格渲染成准确的参考页,并做规范治理」,也可以把 Redocly Redoc CE 的规格支持说明 放进对照:它写明可渲染 OpenAPI 3.2 / 3.1 / 3.0,Swagger 2.0 会在加载时转换成 OpenAPI 3,同时也支持 AsyncAPI、GraphQL,以及写在 OpenAPI 扩展里的 MCP 服务器描述。它更接近参考页渲染器,而不是完整的企业 Wiki;和「概念手册 + 权限交付 + 一源多站」是否同一套系统,要另行验收。

规格版本:先问你的文件能不能被完整渲染

选型演示里「支持 OpenAPI」几乎是标配。真正要写进询价单的是版本清单,以及清单之外的内容会如何失败。
OpenAPI 3.1 已经引入 webhooks。GitBook 明确写了 3.1 的 webhooks;Document360 也写明 3.1 webhook 会出现在参考里,但 Try It! 对 webhook 不可用。若团队的规格已经用上 3.2 的 QUERY 方法、流式响应或 Device Authorization Flow,就要在目标平台上用真实文件做一次导入,而不是只看营销页上的「OpenAPI」字样。GitBook 与 ReadMe 的公开兼容说明尚未把 3.2 写进去,并不等于它们一定无法打开文件,但意味着 3.2 独有字段可能被忽略、告警或导入失败——这些结果只能用你自己的规格验证。
Document360 建议新项目直接使用 3.2,并从 Swagger 2.0 迁过来的团队可以先按原格式导入、再逐步升级。Mintlify 则要求 Swagger 2.0 先转换成 OpenAPI 3。验收时应准备两份样例:一份是当前生产规格,一份是你们计划升级到的最高版本,分别看参考页、试调和下载源文件是否完整。

导入之后,规格改了文档有没有跟上

导入只是起点。接口一周可能合并多次,参考页如果还靠人改,很快就会和代码分叉。
GitBook 的产品说明写明:由 OpenAPI 或 Swagger 生成的参考可以在规格变更后自动更新。若规格是按 URL 引入的,文档站点所在源必须被允许跨域 GET,否则页面会加载失败。Document360 把同步分成三档:本地上传适合偶发更新;URL 导入后可以手动再同步;要在每次规格变更时自动更新,则通过 d360 CLI 接入 CI/CD。它同时写明:API 文档在所有付费方案中可用,每个付费方案包含一个 API 工作区,每个工作区最多创建 3 个 API 参考。超出这个结构,要在立项时就算进附加工作区或拆分策略。
Mintlify 把规格放进文档仓库,或指向公开 HTTPS URL,并在导航里用 openapi 字段引用;规格变更后页面更新。它只支持单个 OpenAPI 文档内部的 $ref,多文件规格要先打包成一份再添加。构建过程从公网拉取 URL 时不带凭证——规格若位于认证之后或内网之中,应改提交到文档仓库。ReadMe 允许在导入的端点上追加 Markdown,并且只要 operationId 不变,再同步后这些补充还在;operationId 或导入被删除,补充内容也会被去掉。验收时要把「自动同步」和「手写补充如何存活」写成两行,不要默认它们总是共存。

试调台要验收的是安全边界,不只是「能不能点一下」

交互式试调让读者不必离开文档就能发出请求,也因此成为新的密钥和数据泄漏面。
GitBook 的 “test it” 由 Scalar 驱动,可在文档页上填写参数并查看结果。Document360 的 Try It! 出现在已发布的知识库站点上,官方说明指出:规格里如果没有正确写明 server 变量和 server URL,站点上可能看不到该功能;若 API 使用 OAuth2 或 OpenID Connect,还要把提供方的 Redirect URI 设为知识库域名下的回调页,并了解会话期间的静默续期。ReadMe 的 API Reference 强调可在文档内发出已认证请求,并提供可运行代码示例。Mintlify 的 playground 可以发送真实请求,包括图片、音频、视频和流式响应,也可以按字段或 JSON 编辑请求体。
三件事要写进验收表。第一,试调默认打到哪一个环境:文档站若只能打生产,演示数据和误操作风险都要单独评估。第二,未登录读者能不能看到完整规格或发出请求。Mintlify 写明:站点如果不要求认证,文档仓库里的 JSON 和 YAML 会按路径出现在文档域名下,例如 https://docs.example.com/openapi.json,即使某份规格没有被写进导航。是否允许读者下载源规格,也应按产品开关单独确认——Document360 用「Show download API source」控制知识库站点上的源文件下载。第三,私有或合作伙伴 API 的参考页,必须和权限与外部共享放在同一条链上验收:文档站的登录、读者组和试调里使用的令牌,不能假定会自动继承。公开试调里不要预填生产密钥。

参考页和概念手册必须能从同一套知识发出去

API 参考解决「这个端点怎么调用」,概念手册解决「先完成认证、再处理分页、最后理解这条错误码」。两者分开维护,是产品手册最常见的分叉来源之一。
GitBook 把「把 API 与产品知识放在一起」写成明确能力,可用站点分区把参考和指南放进同一站点,也可以配自定义域名和认证访问。Document360 虽然给 API 文档准备了独立工作区,但参考页的发布目标是知识库站点,而不是强制再做一个互不相通的门户。ReadMe 的 API Reference 本身就位于开发者中心之中,可与指南并存。Mintlify 允许在导航里把 OpenAPI 参考做成标签页,并与其他页面、甚至 SDK 参考或手写端点页组合。
验收时不要只看「能不能导入 OpenAPI」,还要看:同一版本的概念页能不能链接到同一版本的参考页;切换产品版本或语言时,参考页是否跟着切,还是仍指向默认分支——这要和多版本与多语言发布一起回归。若还要把说明投进产品界面,也应回到产品内嵌帮助的那条标准:内嵌层检索的是已发布的同一份内容,而不是另一份只存在于开发者门户里的摘录。
对需要同时交付对外手册和合作伙伴接口文档的团队来说,这件事对应的是知识资产发布和一源多站:由规格生成的参考页、给实施人员看的概念手册,以及需要登录才能阅读的私有说明,都应是同一套已发布知识在不同分发面上的呈现,而不是三份各改各的文稿。权限交付决定谁能打开私有参考和试调,AI 检索则应落在这份已经发布、且对当前读者可见的内容上。如果你正在做可发布的产品手册或企业 Wiki,欢迎到 Baklib Wiki 看一看,同一套知识资产如何同时服务手册发布、权限交付和 AI 检索。

写进立项书的验收清单

立项或换栈时,把下面九行写成必填项,再用你们自己的规格和一页概念手册做一次并联验收。
  1. 规格版本。 列出当前生产规格和计划升级的版本,确认目标平台公开支持哪些版本,并用真实文件验证 3.1 webhooks、3.2 独有字段是否被完整渲染。
  2. 导入方式。 分清本地上传、URL 引入、仓库内引用和 CI/CD 自动同步,分别记录失败时的日志入口。
  3. 同步延迟与补充内容。 规格合并后参考页多久更新;手写补充绑定在什么标识上,标识变更后会不会丢失。
  4. 同站发布。 概念手册与 API 参考是否在同一站点、同一导航和同一自定义域名下发布,而不是两个互不相通的门户。
  5. 版本与语言对齐。 切换产品版本或语言时,参考页是否指向对应规格,而不是永远停在默认版本。
  6. 试调环境与鉴权。 默认请求打到哪个 server;OAuth 回调、CORS、预填参数和令牌续期如何配置。
  7. 公开与私有边界。 未登录读者能否打开参考页、下载规格或发出请求;私有 API 如何映射到读者组或认证访问。
  8. 对 AI 与 MCP 的暴露。 若启用 MCP 或 llms.txt,确认其来源是已发布、当前读者有权看见的同一份参考与手册,并与既有 MCP、GEO 清单一起回归。
  9. 容量与方案边界。 如 Document360 对工作区和参考数量的限制,或某项能力所属的方案,要在询价时写明,而不是上线后再发现不够用。
最后仍回到那句验收标准:先确认接口规格是可同步的源,再确认参考页和概念手册从同一套已发布知识发出去,并且试调和对外暴露都没有超出当前读者的权限。

常见问题

把 OpenAPI 文件放进 Git 仓库,算不算已经有 API 文档?

不算。仓库里的规格只说明接口有一份机器可读描述,开发者仍要自行用本地工具打开,也不等于已经有一份与概念手册同站发布、可同步更新的参考页。规格是源,文档站上的参考页和试调才是要验收的发布面。

平台写了支持 OpenAPI 3.1,是不是就能完整渲染 3.2 规格?

不能这样默认。OpenAPI 3.2 增加了 QUERY 方法、更细的 querystring 建模、Device Authorization Flow 以及流式响应等描述;GitBook 和 ReadMe 的公开兼容说明写到 3.1,Document360 与 Mintlify 则把 3.2 列入支持清单。即使文件能导入,3.2 独有字段仍可能被忽略或告警。应用你们自己的规格做一次导入验证,而不是只看「支持 OpenAPI」这几个字。

概念手册和 API 参考必须拆成两个站点吗?

不必,也不建议把它们做成互不相通的两套门户。GitBook、Document360、ReadMe 和 Mintlify 都提供把参考页与指南放在同一文档站(或发布到同一知识库站点)的方式。分叉通常来自「参考页自动生成、手册却在另一个域名里手写」。需要不同的导航或权限时,应在同一套已发布知识上做分区或读者组,而不是维护第二份端点说明。

试调台能发真实请求,会不会把密钥暴露给未登录读者?

有可能,所以要单独验收。试调默认打到哪个环境、未登录读者能不能下载规格或发出请求、私有 API 的令牌从哪里来,都应写进运行手册。Mintlify 写明:站点若不要求认证,仓库里的 JSON 和 YAML 会按路径出现在文档域名下。公开试调里不要预填生产密钥;需要登录才能阅读的参考页,应和权限模型一起回归。

规格自动同步之后,手写的补充说明还会在吗?

取决于补充内容绑在什么标识上。ReadMe 写明:追加的 Markdown 只要对应端点的 operationId 不变,再同步后仍会保留;operationId 或导入被删除,补充也会被去掉。GitBook、Document360 和 Mintlify 的自动更新,针对的是由规格生成的参考本身。验收时要把「生成内容如何更新」和「手写补充如何存活」分成两行,不要默认它们总是共存。

相关产品

术语

相关阅读

提交反馈
Baklib Birds
to top icon