# API 文档格式规范标准

## 1. 文档结构规范

### 1.1 文档头部
```markdown
# [系统名称] API 文档 (v[版本号])

## 1. 接口概述

### 1.1 功能范围
- [功能点1]
- [功能点2]
- [功能点3]

### 1.2 基础路径
`/api/v[版本号]/[系统名称]`

### 1.3 权限控制
- 公开接口（无需认证）：[接口描述]
- 管理接口（需要认证）：[接口描述]

### 1.4 全局错误码
| 状态码 | 说明               |
|--------|--------------------|
| 400    | 请求参数无效       |
| 401    | 未授权             |
| 403    | 权限不足           |
| 404    | 资源不存在         |
| 500    | 服务器内部错误     |
```

## 2. 接口定义规范

### 2.1 接口格式
```markdown
### [序号].[序号] [接口名称]
```
[HTTP方法] [接口路径]

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| param1      | string | 是   | 参数说明           |
| param2      | number | 否   | 参数说明           |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}
```

### 2.2 错误响应格式
```json
{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "错误描述信息"
}
```

## 3. 数据类型规范

### 3.1 基本数据类型
- `string`: 字符串类型
- `number`: 数字类型
- `boolean`: 布尔类型
- `array`: 数组类型
- `object`: 对象类型
- `file`: 文件类型

### 3.2 日期时间格式
- 日期: YYYY-MM-DD
- 时间: YYYY-MM-DDTHH:mm:ssZ (ISO 8601)

## 4. 权限控制规范

### 4.1 权限级别
- **公开**: 无需认证即可访问
- **用户**: 需要用户登录认证
- **管理员**: 需要管理员权限
- **系统管理员**: 需要系统管理员权限

### 4.2 权限标识
在接口定义中明确标注所需权限级别

## 5. 版本管理规范

### 5.1 版本号格式
采用语义化版本号: `v主版本号.次版本号.修订号`

### 5.2 版本兼容性
- 主版本号变更: 不兼容的API修改
- 次版本号变更: 向下兼容的功能性新增
- 修订号变更: 向下兼容的问题修正

## 6. 安全规范

### 6.1 数据传输
- 敏感数据必须使用HTTPS加密传输
- 密码等敏感信息需要加密存储

### 6.2 身份认证
- 使用JWT Token进行身份认证
- Token有效期设置合理时间

## 7. 文档维护规范

### 7.1 更新记录
每次文档更新需要记录:
- 更新日期
- 更新内容
- 更新人员

### 7.2 审核机制
- 新增接口需要经过技术负责人审核
- 重大变更需要经过架构师审核

## 8. 示例模板

```markdown
# 示例系统 API 文档 (v1.0.0)

## 1. 接口概述

### 1.1 功能范围
- 用户管理
- 数据查询
- 系统配置

### 1.2 基础路径
`/api/v1/example`

### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：用户管理、系统配置

### 1.4 全局错误码
| 状态码 | 说明               |
|--------|--------------------|
| 400    | 请求参数无效       |
| 401    | 未授权             |
| 403    | 权限不足           |
| 404    | 资源不存在         |
| 500    | 服务器内部错误     |

## 2. 接口明细

### 2.1 获取用户列表
```
GET /users
```

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| page        | number | 否   | 页码(默认1)        |
| limit       | number | 否   | 每页数量(默认10)   |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "user1",
        "email": "user1@example.com"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 10
  }
}
```
```

## 9. 检查清单

- [ ] 文档头部格式符合规范
- [ ] 接口定义格式统一
- [ ] 数据类型标注准确
- [ ] 权限控制明确标注
- [ ] 错误响应格式规范
- [ ] 版本号管理规范
- [ ] 安全要求明确
- [ ] 示例代码完整
```