第 94 篇
如何维护多个 API 版本的文档
API7.ai
2026年07月21日
要点速览
- 每个受支持版本都是一份独立契约。 为每个版本保留自己的参考文档、示例、更新日志和生命周期状态。
- 让读者一眼认出当前版本。 固定位置的版本选择器、规范 URL、醒目的状态标签和按版本搜索,都能减少误用。
- 让文档和 API 同步发布。 在修改生产行为的同一变更中,审阅并自动检查版本化的 OpenAPI 文件、示例和迁移说明。
- 记录如何迁移。 除了各版本的现状,还要列出破坏性变更、前后对照示例、时间点和经过验证的迁移路径。
- 用运行时信号补充门户通知。 标准响应头
Deprecation和Sunset可以提醒不常查看门户的调用方。
API 很少一直停留在第一个版本。认证会改进,资源模型会演进,有些字段会过时,业务规则也会变化。建立另一个 /v2 参考入口并不难;真正难的是同时维护多套准确的文档,让每位读者知道哪套适用于自己。
本文关注多版本的文档体系。关于 URL、请求头和查询参数等版本设计的取舍,请先阅读 API 版本管理策略与最佳实践。
多版本文档难在哪里?
只有一个版本时,一个页面对应一种生产行为。多个版本则形成一张对应表:提供方可能同时在生产支持 v1 和 v2、预览 v3、维护两代 SDK,并在不同地域分批升级。
常见问题包括:
- 搜索结果把读者带到旧版参考页,却没有标明这是旧版。
- 通用快速入门悄悄换成 v2,而部分用户仍依赖 v1。
- 代码选项卡使用了不同于正文的基础 URL 或 Schema。
- 已弃用的操作仍能搜到,却没有链接到替代方案。
- 一项修正影响所有版本,文档却只更新最新版。
- 对应版本尚未覆盖全部环境,文档已经发布。
应把文档当作有版本的产品数据来管理,让每页都能追溯到适用契约。
1flowchart LR
2 C["API contract change"] --> S["Versioned OpenAPI source"]
3 S --> V["Lint and compatibility checks"]
4 V --> D["Versioned reference and guides"]
5 V --> T["Contract and example tests"]
6 D --> P["Developer portal"]
7 T --> P
8 P --> O["Observed production version"]
9 O --> F["Freshness audit"]
10 F --> S
11
12 classDef source fill:#e8f3ff,stroke:#1677ff,color:#102a43;
13 classDef gate fill:#fff7e6,stroke:#d48806,color:#5c3b00;
14 classDef publish fill:#f6ffed,stroke:#389e0d,color:#173b0b;
15 class S,C source;
16 class V,T,F gate;
17 class D,P,O publish;设计能识别版本的信息架构
给每个版本稳定的 URL
版本选择器很有用,但如果只靠客户端状态保存版本,同一个链接就可能指向不同内容。开发者应能收藏、分享和搜索固定对应某份契约的 URL,例如:
1/docs/v1/users/create
2/docs/v2/users/create
3/docs/v3-preview/users/create
不要让 /docs/users/create 随时指向最新版本,除非它明确是一个入口页。如果使用重定向,应说明规则,不要把以前代表某份契约的链接悄悄指向另一份契约。稳定的 URL 也让流量分析和工单更容易解释。
认真设置 canonical。v1 与 v2 的页面描述不同的行为时并非重复页,通常各自声明自己的规范 URL。退役页没有独立的迁移价值且永久重定向时,可以让替代页成为规范页面。
让版本信息始终可见
除了 URL,还应在页头、导航、端点标题和可复制代码中标明版本。状态提示应给出下一步,例如:
v1 已弃用,支持至 2027 年 3 月 31 日。请按升级指南迁移至 v2。
明确区分预览版、当前版、仍受支持、已弃用和已退役。“旧版”不能替代生命周期政策。预览文档还应说明是否可能出现破坏性变更,以及是否支持生产使用。
切换版本时,如果有对应的概念页,应保留读者当前所处的位置;如果没有,带读者去目标版本的入口页并解释原因。
分离通用概念与版本专属契约
账户设置和通用安全指引可能适用于多个版本;端点、Schema、错误清单、SDK 说明和限制往往会变化。无需复制每个页面,关键是明确归类。
| 内容 | 常用策略 | 原因 |
|---|---|---|
| 端点参考 | 按版本维护 | 属于契约 |
| 请求与响应示例 | 按版本维护并测试 | 字段和行为会变化 |
| SDK 设置 | 按 SDK 和 API 的兼容关系维护 | 不同代软件包可能不兼容 |
| 认证概念 | 行为相同时共享 | 避免重复 |
| 更新日志 | 按时间排序,允许按版本筛选 | 便于了解各版本如何演进 |
| 迁移指南 | 对应明确的起点和目标版本 | 让读者知道如何操作 |
| 弃用政策 | 共享 | 统一说明提供方的承诺 |
共享页面也要标出覆盖范围,例如“适用于 v1 及后续版本”。
以契约作为权威来源
每份独立受支持的契约应有自己的 OpenAPI 文件。目录可以很简单:
1contracts/
2 v1/openapi.yaml
3 v2/openapi.yaml
4 v3-preview/openapi.yaml
5docs/
6 shared/
7 migrations/v1-to-v2.md
8 migrations/v2-to-v3.md
9examples/
10 v1/
11 v2/
让工具读取确定的契约文件和发布标识。如果构建读取内容会变的 latest.yaml,就可能误用新 Schema 重新发布旧文档。生成结果应记录 API 版本、源代码提交和构建时间,以便追溯。
在持续集成中做三类检查:
- 结构验证。 检查每份 OpenAPI 文件是否有效、内部链接是否能解析。
- 兼容性分析。 将拟发布的契约与已发布版本比较,发现被移除的操作、收紧的 Schema、新增必填属性或变化的安全要求。
- 行为验证。 向对应版本的测试环境发送文档中的请求,用同一份契约检查响应。
参考文档生成可以减少端点说明与契约的偏差。快速入门、概念说明、迁移取舍和故障排查仍需人工维护。
编写可执行的迁移指南
更新日志告诉读者发生了什么,迁移指南说明调用方要做什么。两者应分别维护。
先交代范围和紧迫性:
- 谁必须迁移?
- 目标版本是什么?
- 何时结束支持?
- 新旧版本能否同时运行?
- 有问题时去哪里求助?
随后用统一格式列出每项破坏性变更:旧行为、新行为、对调用方的影响、需要修改什么和如何验证。用前后对照的请求替代抽象描述。以下使用假设 API 的版本头作示例:
1# v1: version in the path
2GET /v1/orders/ord_123 HTTP/1.1
3Host: api.example.com
4Authorization: Bearer ${ACCESS_TOKEN}
5
6# v2: version selected explicitly by header
7GET /orders/ord_123 HTTP/1.1
8Host: api.example.com
9Authorization: Bearer ${ACCESS_TOKEN}
10X-API-Version: 2026-07-01响应结构变化时,用表格说明字段如何映射,标出移动、类型改变、变为必填或被删除的字段。附上测试清单与回滚条件。迁移周期较长时,应允许团队在切换所有调用方前比较新旧版本的流量或响应。
1sequenceDiagram
2 participant P as API Provider
3 participant D as Documentation Portal
4 participant C as API Consumer
5 participant G as API Gateway
6
7 P->>D: Publish v2 docs and v1-to-v2 guide
8 P->>C: Announce support and sunset dates
9 C->>G: Continue calling v1
10 G-->>C: v1 response plus deprecation signals
11 C->>D: Follow migration and test checklist
12 C->>G: Send canary traffic to v2
13 G-->>C: Validate v2 behavior
14 C->>G: Move production traffic to v2
15 P->>D: Retire v1 reference but keep migration page在文档和响应中通知弃用
门户横幅只能触达打开门户的读者,机器可读的响应元数据可以触达仍在调用的集成。两种渠道可以同时使用。
RFC 9745 定义了 Deprecation 响应头和 deprecation 链接关系。RFC 8594 定义了 Sunset,用于说明资源预计何时停止响应。示例:
1HTTP/1.1 200 OK
2Deprecation: @1798675199
3Sunset: Wed, 31 Mar 2027 23:59:59 GMT
4Link: <https://developer.example.com/migrations/v1-to-v2>; rel="deprecation"; type="text/html"
5Content-Type: application/json弃用表示这个版本不宜用于新的集成,停止服务日期则表示提供方预计它何时不可用。前者用结构化日期,后者用 HTTP 日期;停止服务日期不得早于弃用日期。发送这些响应头本身不会改变资源行为或自动停止服务。
即使路由由多个上游团队维护,也可以在网关层为整组路由一致地添加提示头。通过 API7 企业版 等平台,也可以集中管理版本路由、观察流量和执行策略。详细说明仍以门户为准,网关则负责在运行时提醒,并帮助识别仍在使用旧版的调用方。
不要在弃用监测数据中暴露调用方密钥或内部实现细节。用获准的客户端标识关联用量,能聚合就聚合,并明确保存期限。
建立文档发布流程
每次发布 API 时,文档变更应包括:
- 固定的契约文件和版本标识;
- 渲染后的参考页更新;
- 经测试的请求和响应;
- 破坏性变更报告;
- 更新日志条目;
- 调用方需要采取行动时的迁移指南;
- 最新生命周期日期和支持联系方式;
- 搜索、重定向和导航的调整。
预览整个站点。版本选择器、跨版本链接、全站搜索和复制按钮容易在系统对接处出问题。对所有受支持版本跑链接检查,并检查代码块是否引用了旧主机名、旧版本路径前缀或旧 SDK 包名。
发布后,用生产元数据核对已部署的文档。可以通过轻量检查比对门户、契约注册库、网关路由和支持政策中的版本;如果有出入,应通知负责人。
到了停止服务日期,也不必直接删除所有退役文档。可将旧页面从主导航和搜索中移除,在原有地址保留简短的退役说明,标明退役版本,链接到继任版本和迁移指南,并解释运行时行为,例如 410 Gone。有合规要求或生命周期较长的集成,可能需要在受限环境中保留历史文档更久。
多版本文档核对清单
在宣布某版本就绪之前,确认:
- 每个页面和示例都标明版本;
- 版本拥有稳定、可分享的 URL;
- 契约、文档、SDK 和测试环境一致;
- 搜索结果显示生命周期状态;
- 版本选择器在每个页面都能切换到合适的目标;
- 每项破坏性变更都有迁移说明;
- 各渠道的弃用和停止服务日期一致;
- 文档请求不依赖未交代的设置;
- 旧链接有明确的重定向或退役说明;
- 每个受支持版本都有负责人和复核日期。
小结
一套可靠的多版本文档要说清两件事:当前集成还能依赖什么,接下来需要做什么。稳定的 URL、明确的生命周期状态、按版本维护的契约、可执行的迁移指南和自动检查,可以让这些信息持续准确。
接下来阅读如何使用 OpenAPI 编写 API 文档。要了解从设计到退役的完整流程,可参阅 API 生命周期管理。