接口文档最容易变成“上线前补一下”的材料，但真正影响协作效率的，往往是需求评审、联调、验收这几个节点里没人能确定接口到底长什么样。文档不需要写成大部头，关键是跟着接口生命周期一起更新。
需求阶段先定契约
接口还没写代码时，先确认资源名、请求方式、核心字段、错误码和权限边界。查询接口尽量说明筛选条件、排序规则和分页语义；写接口要说明幂等性、是否允许重复提交，以及失败后前端应该展示什么信息。
这个阶段不要急着抠实现细节，先把“前端能不能按这个契约开发”说清楚。字段如果还没最终确定，可以标为待确认，但不要留下空链接、假地址或含糊的示例。
开发阶段同步变更
接口进入开发后，文档最怕和代码分叉。每次 DTO、枚举、状态流转或权限规则变化，都要顺手同步文档。后端可以把校验规则、默认值、时间字段单位写清楚，前端可以补充页面使用场景和异常状态。
如果项目有 OpenAPI、Apifox、Swagger 或类似工具，建议把自动生成的结构文档当作底稿，再加人工说明。自动文档负责字段列表，人工说明负责业务边界。
联调阶段记录真实样例
联调时最有价值的是“真实请求和真实响应”。可以保留一组成功样例、一组参数错误样例、一组权限失败样例。样例里不要放真实 token、Cookie 或不可公开账号，必要时用本机私有配置保存。
前端遇到错误时，也要把错误码、错误文案和用户动作对应起来。文档里只写“接口报错”没有意义，真正需要的是“用户还可以继续编辑、重试、刷新，还是必须联系管理员”。
发布后留下变更记录
接口上线后，文档至少要记录发布时间、影响页面、兼容状态和后续废弃计划。未上线个人项目可以按正确模型收敛，不必为了临时字段背历史包袱；但只要有外部调用方，就要写清迁移窗口和退出条件。
一个轻量节奏是：需求评审补契约，开发中补字段，联调中补样例，上线后补变更记录。能坚持这个节奏，前后端协作会少很多“你那边是不是没更新”的反复确认。
