# 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  
**状态**: ✅ 已完成