描述
从代码生成全面的开发者友好型 API 文档，包括端点、参数、示例和最佳实践 --- ## 概述 本指南介绍如何从代码自动生成完整、可维护的 API 文档，帮助开发者快速理解和集成接口。 --- ## 核心组件 ### 1. 端点文档结构 | 元素 | 说明 | 示例 | |:---|:---|:---| | HTTP 方法 | GET / POST / PUT / DELETE | `GET /api/v1/users` | | 路径 | 资源定位符 | `/api/v1/users/{id}` | | 功能描述 | 一句话说明用途 | 获取用户详细信息 | | 认证方式 | 所需权限或 Token | `Bearer Token` / `API Key` | ### 2. 参数规范 **路径参数** ```http GET /api/v1/users/{userId}/orders/{orderId} ``` | 参数名 | 类型 | 必填 | 约束 | 说明 | |:---|:---|:---|:---|:---| | `userId` | `string` | 是 | UUID 格式 | 用户唯一标识 | | `orderId` | `string` | 是 | 64 位整数 | 订单编号 | **查询参数** ```http GET /api/v1/users?page=1&limit=20&status=active ``` | 参数名 | 类型 | 必填 | 默认值 | 说明 | |:---|:---|:---|:---|:---| | `page` | `integer` | 否 | `1` | 页码，最小值为 1 | | `limit` | `integer` | 否 | `20` | 每页条数，最大 `100` | | `status` | `string` | 否 | - | 筛选状态：`active` / `inactive` / `pending` | **请求体（JSON）** ```json { "username": "zhangsan", "email": "zhangsan@example.com", "role": "developer", "department": "engineering" } ``` | 字段 | 类型 | 必填 | 验证规则 | 说明 | |:---|:---|:---|:---|:---| | `username` | `string` | 是 | 3-20 字符，仅字母数字下划线 | 登录用户名 | | `email` | `string` | 是 | 符合 RFC 5322 | 联系邮箱 | | `role` | `string` | 是 | 枚举值见下方 | 用户角色 | | `department` | `string` | 否 | - | 所属部门 | --- ## 完整请求示例 ### 创建用户 **请求** ```http POST /api/v1/users HTTP/1.1 Host: api.example.com Content-Type: application/json Authorization: Bearer eyJhbGciOiJIUzI1NiIs... { "username": "zhangsan", "email": "zhangsan@example.com", "role": "developer", "department": "engineering" } ``` **成功响应（201 Created）** ```json { "code": 0, "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "username": "zhangsan", "email": "zhangsan@example.com", "role": "developer", "department": "engineering", "createdAt": "2024-01-15T08:30:00Z", "status": "active" }, "requestId": "req_2024011508300001" } ``` **错误响应（400 Bad Request）** ```json { "code": 1001, "message": "参数验证失败", "details": [ { "field": "email", "error": "邮箱格式不正确" } ], "requestId": "req_2024011508300002" } ``` --- ## 状态码与错误体系 | HTTP 状态码 | 业务码 | 场景 | 处理建议 | |:---|:---|:---|:---| | `200` | `0` | 请求成功 | 正常处理响应数据 | | `201` | `0` | 资源创建成功 | 获取返回的 `id` 进行后续操作 | | `400` | `1001` | 参数校验失败 | 检查 `details` 修正请求参数 | | `401` | `2001` | 认证失败 | 刷新 Token 或重新登录 | | `403` | `2002` | 权限不足 | 确认账号角色或联系管理员 | | `404` | `3001` | 资源不存在 | 核对资源 ID 是否正确 | | `409` | `3002` | 资源冲突 |