mirror of
https://gitee.com/ShopeX/ECShopX_mobile-frontend
synced 2026-08-15 01:46:26 +08:00
176 lines
3.6 KiB
Markdown
176 lines
3.6 KiB
Markdown
# 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. **测试验证，确保准确** |