跳转到正文
API 101
本文目录

第 94 篇

如何维护多个 API 版本的文档

要点速览

  • 每个受支持版本都是一份独立契约。 为每个版本保留自己的参考文档、示例、更新日志和生命周期状态。
  • 让读者一眼认出当前版本。 固定位置的版本选择器、规范 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 版本、源代码提交和构建时间,以便追溯。

在持续集成中做三类检查:

  1. 结构验证。 检查每份 OpenAPI 文件是否有效、内部链接是否能解析。
  2. 兼容性分析。 将拟发布的契约与已发布版本比较,发现被移除的操作、收紧的 Schema、新增必填属性或变化的安全要求。
  3. 行为验证。 向对应版本的测试环境发送文档中的请求,用同一份契约检查响应。

参考文档生成可以减少端点说明与契约的偏差。快速入门、概念说明、迁移取舍和故障排查仍需人工维护。

编写可执行的迁移指南

更新日志告诉读者发生了什么,迁移指南说明调用方要做什么。两者应分别维护。

先交代范围和紧迫性:

  • 谁必须迁移?
  • 目标版本是什么?
  • 何时结束支持?
  • 新旧版本能否同时运行?
  • 有问题时去哪里求助?

随后用统一格式列出每项破坏性变更:旧行为、新行为、对调用方的影响、需要修改什么和如何验证。用前后对照的请求替代抽象描述。以下使用假设 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 生命周期管理。

编辑本篇文章

获取方案