后端服务接口文档编写规范

后端服务接口文档编写规范一、总则规范（一）适用范围。本规范适用于公司所有后端服务接口文档的编写工作，涵盖接口设计、实现、测试等全生命周期文档内容。（二）核心原则。文档必须遵循准确性、完整性、一致性、可读性原则，确保技术团队高效理解和使用接口信息。（三）版本管理。文档需标注版本号、发布日期、修改记录，采用语义化版本控制（主次修订修订号格式）。二、文档结构标准（一）基础要素。每个接口文档必须包含接口基本信息、请求参数、响应数据、异常处理、安全说明五类核心内容。（二）层级划分。一级标题为文档主章节，二级标题为具体内容模块，三级标题为操作步骤或执行标准，严格遵循层级递进关系。（三）附件规范。涉及复杂逻辑的接口需附加流程图、时序图等可视化附件，统一命名为"接口名称附件"格式。三、接口基本信息（一）权责划定。接口提供方负责文档初稿撰写，接口使用方负责内容审核，技术架构组负责最终定稿。（二）信息要素。必须明确接口名称、服务模块、作者信息、创建日期、接口URL、请求方法六项基础信息。（三）命名规范。接口名称需采用动词+名词结构（如"查询订单"），URL路径需使用驼峰式命名法（如"/api/v1/orders"）。四、请求参数规范（一）参数分类。参数分为必填参数、可选参数、请求头参数三类，使用不同颜色或符号区分。（二）参数定义。每个参数需标注名称、类型、描述、示例值、是否可空五项信息，类型需符合JSONSchema规范。（三）校验规则。必须明确参数校验规则，包括长度限制、数值范围、格式要求等，使用正则表达式表述复杂规则。（四）特殊处理。分页参数需标注默认值、最大值，文件上传参数需说明文件类型、大小限制。五、响应数据规范（一）状态码定义。必须定义成功状态码（200）及所有异常状态码（400-599），每个状态码需提供错误码和描述。（二）数据结构。响应体必须采用JSON格式，使用对象嵌套方式表述数据层级关系，关键数据需标注示例值。（三）字段说明。每个字段需说明类型、是否必填、描述、示例值，复杂对象需单独列出字段说明。（四）分页处理。分页接口必须包含total、size、current、pages等通用字段，使用数组封装数据列表。六、异常处理规范（一）异常分类。分为客户端异常（4xx）、服务器异常（5xx）两类，每个异常需提供错误码和详细描述。（二）错误码规则。错误码采用"模块+功能+序号"三级结构（如"USER-001"），保持全公司唯一性。（三）异常响应。异常响应必须包含code、message、timestamp、traceId四项基础信息，traceId用于链路追踪。（四）日志规范。异常处理需记录完整日志，包含请求参数、响应内容、异常堆栈信息，保留30天以上。七、安全说明规范（一）认证方式。必须明确接口认证方式（如JWT、OAuth2、APIKey），提供配置示例和调用示例。（二）权限控制。说明接口访问权限控制逻辑，包括角色权限、资源权限等，使用表格表述权限矩阵。（三）加密要求。明文传输参数必须加密处理，使用HTTPS协议传输，敏感信息需采用AES-256加密。（四）防攻击措施。需说明防SQL注入、防XSS攻击、防重放攻击等措施，提供具体实现方案。八、文档编写标准（一）术语统一。全篇术语必须保持一致，首次出现需标注英文对照，建立术语表附件。（二）格式要求。参数名称使用大驼峰式（如"CreateTime"），描述文字使用主动语态，避免使用模糊词汇。（三）示例规范。每个参数和响应体必须提供JSON示例，复杂对象使用缩进排版，示例代码使用统一缩进风格。（四）更新机制。接口变更需同步更新文档，重大变更需发布新版本，历史版本保留存档。九、评审与发布（一）评审流程。文档需经过提供方自审、使用方复审、架构组终审三道流程，每个环节需记录评审意见。（二）发布标准。文档发布需附带版本说明，使用GitLab或Jira等工具管理版本，提供在线预览功能。（三）培训要求。新接口文档需组织技术培训，使用方需签署确认函，确保理解接口核心逻辑。（四）维护责任。接口文档维护责任分配到具体开发人员，建立文档更新看板跟踪进度。十、附则说明（一）文档模板。提供标准Word模板和Swagger模板，模板需包含所有必填元素，禁止修改模板结构。（二）检查清单。编写完成后需对照检查清单逐项确认，清单包含32项检查项，分为必填项和推荐项。（三）违规处理。文