软件接口文档编写规范（完整版）.docxVIP

软件接口文档编写规范（完整版）

第一章编写基本要求

一、通用编写原则

1.准确性要求

所有接口文档描述内容必须和实际接口运行行为100%一致，禁止出现参数名写错、取值范围标注错误、返回示例和实际返回结果不匹配的问题。所有参数的取值范围必须精确到具体枚举值，禁止使用“其他”“相关”等模糊表述，接口文档更新延迟不能超过2个工作日，未按要求编写的接口，测试环节有权直接打回，不予进入上线审批流程。涉及对外公开的接口，所有描述内容必须经过至少2轮交叉校验，避免对接方按照文档调试时出现逻辑冲突。

2.完整性要求

接口文档必须覆盖所有请求参数、所有返回字段、所有异常状态码，不能遗漏任何必填项。单接口文档内容缺失率超过5%的直接判定为不合格，需要开发人员重新编写。对于可选参数，必须明确标注不传参数时服务端的默认处理逻辑，比如不传用户头像字段时，服务端是否返回系统默认占位图，不能仅标注该参数非必填。

3.可读性要求

文档所有描述内容使用简体中文，避免使用生僻技术术语，对接方的普通开发人员阅读后不需要额外询问接口开发人员就能完成对接调试。所有字段的说明长度控制在200字符以内，避免大段文字堆砌，涉及特殊逻辑的部分可以单独附1-2行补充说明，不要把无关的业务背景内容塞进接口说明里。

4.可追溯性要求

每一次接口文档的变更都必须留下完整记录，所有历史版本的文档都要永久留存，不能直接覆盖旧版本内容