# API 文档格式检查清单

## 1. 文档结构检查

### 1.1 文档头部
- [ ] 文档标题包含系统名称和版本号：`# 系统名称 API 文档 (vX.Y.Z)`
- [ ] 版本号采用语义化版本格式：`v主版本.次版本.修订号`

### 1.2 接口概述
- [ ] 包含功能范围说明（1.1）
- [ ] 包含基础路径说明（1.2）：`/api/vX/系统名称`
- [ ] 包含权限控制说明（1.3）
- [ ] 包含全局错误码表格（1.4）

### 1.3 接口明细
- [ ] 接口按功能模块分组（2.x）
- [ ] 每个接口有清晰的序号和名称
- [ ] 接口路径使用相对路径（基于基础路径）

### 1.4 版本历史
- [ ] 包含版本历史章节
- [ ] 每个版本有更新日期和说明

## 2. 接口定义检查

### 2.1 请求参数
- [ ] 使用表格格式定义请求参数
- [ ] 包含参数名、类型、必填、说明四列
- [ ] 参数类型使用标准类型：string、number、boolean、array、object、file
- [ ] 必填字段明确标注：是/否

### 2.2 响应格式
- [ ] 统一使用标准响应格式：
  ```json
  {
    "status": "success",
    "data": {}
  }
  ```
- [ ] 错误响应格式：
  ```json
  {
    "status": "error",
    "code": "ERROR_CODE",
    "message": "错误描述"
  }
  ```

### 2.3 代码块格式
- [ ] HTTP方法使用大写：GET、POST、PUT、DELETE
- [ ] 接口路径使用反引号包裹
- [ ] JSON示例格式正确，缩进一致

## 3. 内容质量检查

### 3.1 准确性
- [ ] 接口路径与实际实现一致
- [ ] 参数定义准确无误
- [ ] 响应示例真实有效

### 3.2 完整性
- [ ] 包含所有必要的接口
- [ ] 参数说明详细完整
- [ ] 错误处理描述清晰

### 3.3 一致性
- [ ] 术语使用一致
- [ ] 格式风格统一
- [ ] 命名规范一致

## 4. 格式规范检查

### 4.1 Markdown格式
- [ ] 标题层级正确（# ## ###）
- [ ] 表格格式规范
- [ ] 代码块语言标识正确
- [ ] 列表格式一致

### 4.2 文字质量
- [ ] 无拼写错误
- [ ] 无语法错误
- [ ] 描述清晰易懂
- [ ] 专业术语准确

## 5. 安全检查

### 5.1 权限控制
- [ ] 明确标注接口权限要求
- [ ] 敏感接口有安全说明
- [ ] 认证方式描述清晰

### 5.2 数据安全
- [ ] 敏感数据加密要求
- [ ] 数据传输安全说明
- [ ] 访问控制描述

## 6. 版本管理检查

### 6.1 版本兼容性
- [ ] 版本变更说明清晰
- [ ] 向后兼容性考虑
- [ ] 废弃接口标注

### 6.2 更新记录
- [ ] 更新日期准确
- [ ] 变更内容详细
- [ ] 影响范围说明

## 7. 使用说明

### 7.1 检查流程
1. 使用脚本批量检查：`python scripts/update_api_docs.py`
2. 人工复核检查清单
3. 记录不符合项并整改
4. 验证整改结果

### 7.2 检查频率
- 新接口开发：开发完成后立即检查
- 接口变更：变更后立即检查
- 定期检查：每月一次全面检查

### 7.3 检查责任人
- 开发工程师：接口开发时自查
- 技术负责人：代码审查时检查
- 架构师：定期全面检查

## 8. 常见问题

### 8.1 格式问题
- 缺少版本号
- 权限控制不明确
- 响应格式不统一
- 参数定义不完整

### 8.2 内容问题
- 接口描述不清晰
- 示例代码错误
- 错误处理缺失
- 安全要求不明确

### 8.3 维护问题
- 版本更新不及时
- 变更记录缺失
- 兼容性说明不足

## 9. 附录

### 9.1 标准模板
```markdown
# 系统名称 API 文档 (v1.0.0)

## 1. 接口概述

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

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

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

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

## 2. 接口明细

### 2.1 获取数据
```
GET /data
```

**请求参数**:
| 参数名      | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| id          | string | 是   | 数据ID             |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "id": "123",
    "name": "示例数据"
  }
}
```

## 3. 版本历史

### v1.0.0 (2024-01-20)
- 新增: 初始版本发布
- 功能: 基础数据接口
```

### 9.2 检查记录表
| 检查日期 | 检查人 | 文档名称 | 问题描述 | 整改状态 | 备注 |
|----------|--------|----------|----------|----------|------|
| 2024-01-20 | 张三 | dashboard.md | 缺少版本号 | 已整改 |      |
| 2024-01-20 | 李四 | farming.md | 响应格式不统一 | 已整改 |      |

### 9.3 相关文档
- [API文档格式规范标准](../API_DOCUMENTATION_STANDARD.md)
- [文档更新与审核机制](../DOCUMENTATION_MAINTENANCE_PROCESS.md)
- [API文档批量更新脚本](../../scripts/update_api_docs.py)

## 10. 修订记录

| 版本 | 修订日期 | 修订内容 | 修订人 |
|------|----------|----------|--------|
| v1.0 | 2024-01-20 | 初始版本 | 架构师 |
| v1.1 | 2024-01-20 | 增加检查项说明 | 架构师 |

**生效日期**: 2024年1月20日