上周帮朋友改一个微信小程序后端，他边敲代码边叹气：‘又得花半天写 Swagger 注释，还老被前端吐槽字段没写全……’其实真没必要硬扛——现在有好几个成熟的 API 文档开源项目，搭好就能自动生成、实时预览、还能嵌进 CI 流程里。
Swagger UI：老牌但够稳，适合 Java/Node/Python 项目
Swagger（现归 OpenAPI 规范）仍是大多数团队的第一选择。你只要在代码里加几行注释，比如 Spring Boot 项目中：
@Api(value = "用户管理", tags = "User Controller")
@PostMapping("/users")
public Result<User> createUser(@ApiParam("用户基本信息") @RequestBody User user) { ... }配合 springdoc-openapi-ui 依赖，启动服务后直接访问 /swagger-ui.html，就出来带交互调试框的页面，前端点点就能试接口，连 curl 命令都给你生成好了。
Postman + OpenAPI 导入：适合已有 Postman 集合的团队
如果你或测试同事已经在用 Postman 写请求，别急着重写文档。Postman 支持导出为 OpenAPI 3.0 JSON/YAML，再丢进 Redoc（一个轻量级开源文档渲染器），一行命令就能起个静态页：
npx redoc-cli serve openapi.yaml生成的页面清爽无干扰，支持响应示例折叠、错误码高亮，手机上看也舒服。我们组把 Redoc 页面挂到公司内网 nginx，地址发群里，新人第一天就能查接口。
apidoc：靠注释生成，PHP/JS 老项目救星
有些老 PHP 或 JS 项目根本没上 Swagger，改框架成本太高？试试 apidoc。它不依赖框架，只认你写的特殊注释块：
/**
* @api {get} /user/:id 请求用户信息
* @apiParam {Number} id 用户ID
* @apiSuccess {String} name 用户姓名
*/装完 npm 包，执行 apidoc -i src/ -o doc/，立马生成带搜索、版本切换的 HTML 文档。我们接手一个维护了五年的 Node 后台，三天就把全部接口补全了文档，连历史字段变更都加了 @apiDeprecated 标记。
小技巧：文档和代码别脱节
光有工具不够，得让它活起来。我们在 GitLab CI 里加了一步：
每次 push 到 main 分支，自动运行文档生成脚本，把新 HTML 推到 docs 子目录，并触发 GitHub Pages 更新。这样前端拉最新代码时，顺手点开 https://xxx.github.io/docs 就是最准的接口说明——谁改了字段、谁删了接口，一目了然。
文档不是交付前才补的作业，而是每天写代码时顺手留下的路标。选一个顺手的开源项目，今天下午就配好，明天接口联调时，你就多出半小时喝咖啡。