常见的接口文档写作方式
开发一个项目，前后端对接少不了。接口文档就成了沟通的“桥梁”。那这东西到底用什么写？其实没有固定答案，关键看团队习惯和项目需求。
直接用 Markdown 写
不少小团队或者个人开发者喜欢用 Markdown 写接口文档。语法简单，上手快，配合 GitHub 或 Gitee 就能直接托管展示。
比如这样描述一个登录接口：
# POST /api/login
**请求参数**
- username: 字符串，必填
- password: 字符串，必填
**返回示例**
{
"code": 0,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIs..."
}
}写完推到仓库，链接一发，前端就能看。适合轻量协作，不需要复杂功能。
用 Swagger（OpenAPI）自动生成
如果项目是用 Spring Boot、Express 或者 FastAPI 这类框架，集成 Swagger 特别方便。写好注解，启动服务后自动出文档页面。
比如在 Java 里加个 @ApiOperation 注解，接口说明就出来了。前端打开 http://localhost:8080/swagger-ui.html 就能看到所有接口，还能在线测试。
这种方式省事，而且文档和代码同步更新，不容易脱节。
使用专门的文档工具
有些团队追求更专业的展示效果，会选像 Apifox、YApi、Postman 这类工具。
拿 Apifox 举例，它能把接口管理、文档生成、调试、Mock 数据全包了。后端导入接口后，前端登录就能看到实时文档，还能自己模拟返回数据做联调。
Postman 也不少人用，建个 Collection，每个请求写清楚参数和说明，共享给团队成员。导出成网页链接，开会时直接投屏讲接口逻辑。
企业级项目可能用 Confluence + 插件
大公司内部常用 Confluence 写文档，接口部分也不例外。配合 REST API 插件，可以嵌入真实请求示例，支持评论和版本记录。
好处是权限控制细，谁改了哪一行都有记录。缺点是得维护页面，手动更新容易漏。
代码里写注释，生成文档
还有一种做法是在代码里写结构化注释，用工具提取生成文档。比如 Node.js 项目用apidoc，Python 用 Sphinx + sphinx-apidoc。
写代码的同时把注释放进去：
/**
* @api {post} /user/create 创建用户
* @apiName CreateUser
* @apiGroup User
* @apiParam {String} name 用户名
* @apiParam {Number} age 年龄
*/运行 apidoc 命令，自动生成一套静态网页文档。适合对自动化要求高的项目。
选择哪种方式，看实际场景
一个人接私活，用 Markdown + GitHub 完全够用；团队开发推荐 Swagger 或 Apifox，减少沟通成本；要是公司有统一知识库，Confluence 也跑不掉。
重点不是用什么工具，而是让文档及时更新、清晰可读。再好的工具，写完不维护，最后还是得靠口头传话。”