147 lines
3.4 KiB
Markdown
147 lines
3.4 KiB
Markdown
# Swagger 接口更新说明
|
||
|
||
## ✅ 问题已解决
|
||
|
||
**问题**: `GET /api/v1/assets/mints/:order_id` 接口没有出现在 Swagger 文档上
|
||
|
||
**原因**: Swagger 文档需要重新生成才能包含新添加的接口
|
||
|
||
**解决**: 已更新 Swagger 注释并重新生成文档
|
||
|
||
---
|
||
|
||
## 📝 更新内容
|
||
|
||
### 1. 完善 Swagger 注释
|
||
|
||
在 `backend/gateway/controller/asset_controller.go` 中更新了 `GetMintOrder` 方法的 Swagger 注释：
|
||
|
||
```go
|
||
// GetMintOrder 查询铸造订单状态
|
||
// @Summary 查询铸造订单状态
|
||
// @Description 查询指定铸造订单的状态和详细信息。订单状态包括：PROCESSING（处理中）、SUCCESS（成功）、FAILED（失败）。成功时会返回关联的资产信息，包括 cover_url_signed（预签名URL）和 tx_hash（交易哈希）。
|
||
// @Tags assets
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Security BearerAuth
|
||
// @Param order_id path string true "订单ID（UUID格式）"
|
||
// @Success 200 {object} response.Response{data=dto.GetMintOrderResponseDTO} "成功返回订单和资产信息"
|
||
// @Failure 400 {object} response.Response "参数错误"
|
||
// @Failure 401 {object} response.Response "未授权"
|
||
// @Failure 404 {object} response.Response "订单不存在"
|
||
// @Router /api/v1/assets/mints/{order_id} [get]
|
||
```
|
||
|
||
### 2. 重新生成 Swagger 文档
|
||
|
||
执行了 `swag init` 命令重新生成 Swagger 文档：
|
||
- `docs/docs.go`
|
||
- `docs/swagger.json`
|
||
- `docs/swagger.yaml`
|
||
|
||
### 3. 重启 Gateway
|
||
|
||
重启了 Gateway 服务以加载新的 Swagger 文档。
|
||
|
||
---
|
||
|
||
## ✅ 验证结果
|
||
|
||
### Swagger UI 访问
|
||
|
||
访问地址：http://localhost:8080/swagger/index.html
|
||
|
||
### 接口验证
|
||
|
||
通过 API 验证，`/api/v1/assets/mints/{order_id}` 路径现在包含：
|
||
|
||
- ✅ **GET 方法**: 查询铸造订单状态
|
||
- ✅ **DELETE 方法**: 取消铸造订单
|
||
|
||
### 验证命令
|
||
|
||
```bash
|
||
curl -s "http://localhost:8080/swagger/doc.json" | python3 -c "
|
||
import sys, json
|
||
data = json.load(sys.stdin)
|
||
path = data['paths'].get('/api/v1/assets/mints/{order_id}', {})
|
||
print('GET 方法:', 'get' in path)
|
||
print('DELETE 方法:', 'delete' in path)
|
||
print('GET summary:', path.get('get', {}).get('summary', 'N/A'))
|
||
"
|
||
```
|
||
|
||
**输出**:
|
||
```
|
||
GET 方法: True
|
||
DELETE 方法: True
|
||
GET summary: 查询铸造订单状态
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 接口详情
|
||
|
||
### GET /api/v1/assets/mints/{order_id}
|
||
|
||
**功能**: 查询铸造订单状态
|
||
|
||
**请求**:
|
||
- **方法**: GET
|
||
- **路径参数**:
|
||
- `order_id` (string, required): 订单ID（UUID格式）
|
||
- **认证**: Bearer Token
|
||
|
||
**响应**:
|
||
- **200**: 成功返回订单和资产信息
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"order": {
|
||
"order_id": "xxx",
|
||
"status": "PROCESSING|SUCCESS|FAILED",
|
||
"cover_url": "...",
|
||
"cover_url_signed": "...",
|
||
"tx_hash": "..."
|
||
},
|
||
"asset": {
|
||
"asset_id": 1,
|
||
"cover_url": "...",
|
||
"cover_url_signed": "...",
|
||
"status": 1
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**状态说明**:
|
||
- `PROCESSING`: 处理中（AI 生成中）
|
||
- `SUCCESS`: 成功（已生成封面图并上链）
|
||
- `FAILED`: 失败（包含 `error_message` 字段）
|
||
|
||
---
|
||
|
||
## 🔄 后续更新方法
|
||
|
||
如果修改了接口注释，需要重新生成 Swagger 文档：
|
||
|
||
```bash
|
||
cd /Users/apple/Desktop/web3/TopFans/backend
|
||
bash update-swagger.sh
|
||
```
|
||
|
||
或者手动执行：
|
||
|
||
```bash
|
||
cd backend/gateway
|
||
swag init --parseDependency --parseInternal --parseDepth 1 --output ./docs
|
||
# 然后重启 Gateway
|
||
```
|
||
|
||
---
|
||
|
||
**更新时间**: 2026-01-22
|
||
**状态**: ✅ 已完成
|