ECShopX_mobile-frontend/docs/api-doc-quick-reference.md

API文档生成快速参考

🚀 快速开始

1. 代码分析

# 搜索接口定义
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. 文档生成

{
  "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

🔧 常用工具命令

搜索工具

# 语义搜索
codebase_search "订单详情接口"

# 精确搜索
grep_search "order_id"

# 文件搜索
file_search "trade.js"

文档工具

# 创建文档
edit_file "新接口文档.json"

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

# 删除文档
delete_file "过时文档.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"
      }
    }
  }
}

字段定义

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

✅ 质量检查清单

完整性

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

一致性

• 字段命名与代码一致
• 数据类型与代码一致
• 枚举值与代码一致

可用性

• 可以直接导入Apifox
• 字段映射关系清晰
• 错误响应定义完整

🚨 常见问题

字段缺失

• 检查代码中是否遗漏
• 确认字段是否真的不需要

数据类型错误

• 查看代码中的实际类型
• 确认API响应的真实格式

必填字段判断

• 分析页面使用情况
• 确认缺失是否导致错误

📚 相关文档

• 完整规则文档
• 订单详情接口文档
• 订单详情必填字段说明

🎯 最佳实践

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