还在手动同步文档？用 Git 和 OpenAPI 让它自动跑起来！

网罗开发 （小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
大家好，我是展菲！
全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

摘要

很多团队都有这样的经历：API 改了，但文档没跟上，开发联调时一脸懵。这种文档与代码脱节的情况，不仅影响效率，还容易引发严重 bug。本文将探讨一种更稳妥的解决思路，让你的接口文档和代码版本实现真正的“同步演进”。

引言

当我们在开发中频繁变更接口时，最常被忽略的往往是文档的同步更新。你改了个字段、换了个 path，但忘了同步 OpenAPI 文件或者没有版本区分。结果？测试同学抓狂，前端同学报错连连，线上的老版本也跟着中枪。

那么，能不能做到“改一次接口，文档也随之同步”，甚至还能保留旧版文档供查阅？答案是：完全可以。本文就来聊聊怎么做。

文档与代码版本联动的三板斧

使用 Git 分支或 Tag 管理版本

最简单直观的做法就是：让接口文档和代码一样，跟随 Git 分支走。

• 每个发布版本使用一个 Git Tag（如 v1.0.0）。

• 每次接口更新时，连同 OpenAPI 文件一起提交并打 Tag。

• 文档系统支持加载不同 tag 或分支的文档内容。

这样，想看哪个版本的接口文档，就切到对应 tag 就好。

# 示例：切换到 v1.2.0 版本查看文档
git checkout tags/v1.2.0

# 项目中约定文档路径
openapi/
├── openapi.yaml   # 最新版本
├── v1.0.0.yaml    # 历史版本
├── v1.2.0.yaml

路径版本化策略（URL versioning）

再一种更实用的方式就是在接口路径中加入版本号。例如：

GET /api/v1/users
GET /api/v2/users

路径一旦定义，后续版本不会影响之前的逻辑。你可以：

• 保留 /v1/ 接口供老系统使用；

• 让 /v2/ 接口提供新功能；

• 文档可以清晰标注哪些是哪个版本的接口。

这个策略在大公司接口稳定性要求高的场景中用得特别多。

利用 OpenAPI 的 version 字段管理

OpenAPI（Swagger）规范里自带 info.version 字段，可以非常自然地表示文档的当前版本。

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0

配合 Swagger UI / Redoc 等文档系统，还能切换查看不同版本的文档文件。

Node.js + Swagger + Git Tag 版本文档系统

我们用 Express 写个简单 Demo，搭配 Swagger + Git Tag 模拟多个版本接口文档。

初始化项目

mkdir api-version-demo && cd api-version-demo
npm init -y
npm install express swagger-ui-express yamljs

编写主程序 index.js

const express = require('express')
const swaggerUi = require('swagger-ui-express')
const YAML = require('yamljs')

const app = express()

// 加载不同版本的文档
const v1Doc = YAML.load('./docs/v1.yaml')
const v2Doc = YAML.load('./docs/v2.yaml')

// 提供接口文档路径
app.use('/docs/v1', swaggerUi.serve, swaggerUi.setup(v1Doc))
app.use('/docs/v2', swaggerUi.serve, swaggerUi.setup(v2Doc))

app.listen(3000, () => {
  console.log('API 文档服务启动：http://localhost:3000/docs/v1')
})

3. 分版本编写 docs/v1.yaml 和 docs/v2.yaml

# v1.yaml
info:
  title: Demo API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功返回

# v2.yaml
info:
  title: Demo API
  version: 2.0.0
paths:
  /users:
    get:
      summary: 获取用户列表（新接口）
      responses:
        '200':
          description: 成功返回，增加分页信息

QA 环节

Q: 每次都手动复制一份文档版本文件，有点麻烦？

A: 可以写个脚本自动生成，也可以借助 CI 工具（如 GitHub Actions）在打 Tag 时自动生成一个历史版本副本。

Q: 接口变更多了，有没有更好的方式自动化？

A: 用代码注解生成 OpenAPI 文档（如 swagger-jsdoc、springdoc），可以最大限度降低手动维护成本。

Q: 文档多版本管理会不会影响部署效率？

A: 通常只在文档服务中做版本切换，核心接口逻辑仍走最新版本，不影响主服务性能。

总结

接口文档和代码版本同步，不是难题，只是大多数团队没时间做规范化管理。一旦做到这几点：

• 代码 + 文档打 Tag；

• 接口路径版本化；

• OpenAPI 明确标注版本号；

你就能从根本上解决文档错乱、版本冲突的问题。

未来展望

后续可以探索：

• 文档自动化部署到 S3 / GitHub Pages；

• 和 CI/CD 流程打通，打 tag 自动发布文档；

• 接口变更通知机制，开发人员自动收到 diff。