API接口文档编写规范

API文档编写规范

一、文档结构

• 接口概述：功能说明
• 请求方式与URL
• 请求参数：名称、类型、必填、说明
• 响应格式：字段名、类型、说明
• 错误码表
• 请求示例

二、工具选择

• Swagger/OpenAPI：代码生成文档
• Apifox：API设计+文档+测试
• YApi：国内开源方案

三、命名规范

• URL使用小写+连字符
• 参数使用驼峰命名
• 状态码统一规范

四、版本管理

API版本化（/api/v1/），文档与代码同步更新，变更记录清晰。

相关文章推荐