写好接口文档

文档是接口的一部分。文档不清，等于接口不可用。

推荐结构模板

1. 接口名称与一句话用途
2. 方法 + 路径
3. 请求参数表（必填/可选/类型/示例/默认值）
4. 成功返回示例
5. 失败返回示例
6. 调用示例（curl / JS / 任意一种）
7. 注意事项（限流、鉴权、缓存）

写作技巧

• 用真实例子：参数填「hello」不如填业务相关示例。
• 写失败路径：只写成功示例的文档，联调时最容易翻车。
• 保持同步：代码改字段，文档同一提交更新。
• 降低黑话：必要时解释术语，面向对接方而不是只写给自己。