xiaoyu/topfans

Fork 0

zerosaturation 06f4038a75 提交后端代码

2026-04-07 22:29:48 +08:00

3.4 KiB

Raw Permalink Blame History

Swagger 接口更新说明

✅ 问题已解决

问题: GET /api/v1/assets/mints/:order_id 接口没有出现在 Swagger 文档上

原因: Swagger 文档需要重新生成才能包含新添加的接口

解决: 已更新 Swagger 注释并重新生成文档

📝 更新内容

1. 完善 Swagger 注释

在 backend/gateway/controller/asset_controller.go 中更新了 GetMintOrder 方法的 Swagger 注释：

// 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 方法: 取消铸造订单

验证命令

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: 成功返回订单和资产信息

{
  "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 文档：

cd /Users/apple/Desktop/web3/TopFans/backend
bash update-swagger.sh

或者手动执行：

cd backend/gateway
swag init --parseDependency --parseInternal --parseDepth 1 --output ./docs
# 然后重启 Gateway

更新时间: 2026-01-22
状态: ✅ 已完成

3.4 KiB Raw Permalink Blame History Unescape Escape