# API文档生成快速参考

## 🚀 快速开始

### 1. 代码分析
```bash
# 搜索接口定义
grep_search "api\.trade\.detail" "src/api/*.js"

# 查看页面使用
read_file "src/subpages/trade/detail.js" 100 200

# 分析字段使用
grep_search "info\." "src/subpages/trade/detail.js"
```

### 2. 字段分类
- **必填字段**: 页面渲染必需，业务逻辑必需
- **条件必填**: 基于特定条件必须（如自提订单的ziti_info）
- **可选字段**: 增强功能，统计展示

### 3. 文档生成
```json
{
  "type": "object",
  "required": ["字段1", "字段2"],
  "properties": {
    "字段名": {
      "type": "数据类型",
      "description": "中文描述",
      "example": "示例值"
    }
  }
}
```

## 📋 必填字段判断标准

### 页面渲染必需
- 订单状态显示：`order_status`
- 商品列表：`items` 数组
- 收货地址：`receiver_*` 系列
- 价格计算：`total_fee`, `item_fee_new`

### 业务逻辑必需
- 支付处理：`pay_type`, `pay_channel`
- 配送状态：`delivery_status`, `receipt_type`
- 售后处理：`can_apply_aftersales`

### 用户体验必需
- 订单跟踪：`auto_cancel_seconds`
- 操作权限：`can_apply_cancel`

## 🔧 常用工具命令

### 搜索工具
```bash
# 语义搜索
codebase_search "订单详情接口"

# 精确搜索
grep_search "order_id"

# 文件搜索
file_search "trade.js"
```

### 文档工具
```bash
# 创建文档
edit_file "新接口文档.json"

# 更新文档
search_replace "旧内容" "新内容"

# 删除文档
delete_file "过时文档.json"
```

## 📝 文档结构模板

### 基础结构
```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "接口名称",
    "description": "基于项目代码分析的实际字段使用情况",
    "version": "1.0.0"
  },
  "paths": {
    "/api/path": {
      "get": {
        "summary": "接口摘要",
        "description": "详细描述",
        "operationId": "操作ID",
        "tags": ["标签"],
        "parameters": [],
        "responses": {},
        "security": [{"BearerAuth": []}]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}
```

### 字段定义
```json
{
  "type": "object",
  "required": ["必填字段"],
  "properties": {
    "字段名": {
      "type": "string|integer|number|boolean|array|object",
      "description": "字段描述",
      "example": "示例值",
      "enum": ["值1", "值2"]
    }
  }
}
```

## ✅ 质量检查清单

### 完整性
- [ ] 所有必填字段已标记
- [ ] 字段描述完整准确
- [ ] 示例值合理有效
- [ ] 数据类型正确

### 一致性
- [ ] 字段命名与代码一致
- [ ] 数据类型与代码一致
- [ ] 枚举值与代码一致

### 可用性
- [ ] 可以直接导入Apifox
- [ ] 字段映射关系清晰
- [ ] 错误响应定义完整

## 🚨 常见问题

### 字段缺失
- 检查代码中是否遗漏
- 确认字段是否真的不需要

### 数据类型错误
- 查看代码中的实际类型
- 确认API响应的真实格式

### 必填字段判断
- 分析页面使用情况
- 确认缺失是否导致错误

## 📚 相关文档

- [完整规则文档](./api-documentation-rules.md)
- [订单详情接口文档](../订单详情接口文档-Apifox.json)
- [订单详情必填字段说明](../订单详情接口必填字段说明.md)

## 🎯 最佳实践

1. **先分析代码，再写文档**
2. **必填字段要谨慎判断**
3. **使用中文描述，便于理解**
4. **定期更新，保持同步**
5. **测试验证，确保准确**