tyapi-server/docs/swagger/README.md

# TYAPI Server Swagger 文档

## 📖 概述

本项目使用 [Swaggo](https://github.com/swaggo/swag) 自动生成 Swagger/OpenAPI 文档，提供完整的 API 接口文档和在线测试功能。

## 🚀 快速开始

### 1. 启动服务器

```bash
# 开发模式启动
make dev

# 或者直接运行
go run cmd/api/main.go
```

### 2. 访问文档

启动服务器后，可以通过以下地址访问 API 文档：

-   **Swagger UI**: http://localhost:8080/swagger/index.html
-   **API 文档信息**: http://localhost:8080/api/docs
-   **重定向地址**: http://localhost:8080/docs

## 📝 文档更新

### 自动更新

使用提供的脚本快速更新文档：

```powershell
# Windows PowerShell
.\scripts\update-docs.ps1

# 更新文档并重启服务器
.\scripts\update-docs.ps1 -Restart

# 查看帮助
.\scripts\update-docs.ps1 -Help
```

### 手动更新

```bash
# 使用 Makefile
make docs

# 或者直接使用 swag 命令
swag init -g cmd/api/main.go -o docs/swagger --parseDependency --parseInternal
```

## 🔧 开发指南

### 添加新的 API 接口

1. **在 Handler 方法上添加 Swagger 注释**：

```go
// @Summary 接口简短描述
// @Description 接口详细描述
// @Tags 标签分组
// @Accept json
// @Produce json
// @Security Bearer  # 如果需要认证
// @Param request body dto.RequestStruct true "请求参数描述"
// @Param id path string true "路径参数描述"
// @Param page query int false "查询参数描述"
// @Success 200 {object} dto.ResponseStruct "成功响应描述"
// @Failure 400 {object} map[string]interface{} "错误响应描述"
// @Router /api/v1/your-endpoint [post]
func (h *YourHandler) YourMethod(c *gin.Context) {
    // Handler实现
}
```

2. **为 DTO 结构体添加注释和示例**：

```go
// @Description 请求参数描述
type RequestStruct struct {
    Name string `json:"name" example:"张三"`
    Age  int    `json:"age" example:"25"`
}

// @Description 响应参数描述
type ResponseStruct struct {
    ID   string `json:"id" example:"123e4567-e89b-12d3-a456-426614174000"`
    Name string `json:"name" example:"张三"`
}
```

3. **重新生成文档**：

```bash
make docs
```

### Swagger 注释语法

#### 基础注释

-   `@Summary`: 接口摘要（在文档列表中显示）
-   `@Description`: 详细描述（支持多行）
-   `@Tags`: 标签分组（用于在 UI 中分组显示）

#### 请求/响应格式

-   `@Accept`: 接受的内容类型（json, xml, plain, html, mpfd, x-www-form-urlencoded）
-   `@Produce`: 响应的内容类型（json, xml, plain, html）

#### 安全认证

-   `@Security Bearer`: JWT 认证
-   `@Security ApiKeyAuth`: API Key 认证

#### 参数定义

-   `@Param`: 定义请求参数
    -   路径参数：`@Param id path string true "用户ID"`
    -   查询参数：`@Param page query int false "页码"`
    -   请求体：`@Param request body dto.RequestStruct true "请求参数"`

#### 响应定义

-   `@Success`: 成功响应
-   `@Failure`: 错误响应

## 📋 API 分组

当前文档按以下标签分组：

### 🔐 用户认证

-   用户注册
-   用户登录（密码/短信验证码）
-   发送验证码

### 👤 用户管理

-   获取用户信息
-   修改密码

### 👨‍💼 管理员认证

-   管理员登录

### 🏢 管理员管理

-   创建管理员
-   更新管理员信息
-   修改管理员密码
-   获取管理员列表
-   获取管理员详情
-   删除管理员
-   获取管理员统计

### 🏢 企业认证

-   创建认证申请
-   上传营业执照
-   获取认证状态
-   获取进度统计
-   提交企业信息
-   发起人脸验证
-   申请合同
-   获取认证详情
-   重试认证步骤

### 💰 钱包管理

-   创建钱包
-   获取钱包信息
-   更新钱包信息
-   钱包充值
-   钱包提现
-   钱包交易
-   获取钱包统计

### 🔑 用户密钥管理

-   创建用户密钥
-   获取用户密钥
-   重新生成访问密钥
-   停用用户密钥

## 🔐 认证说明

### JWT 认证

大部分 API 接口需要 JWT 认证，在 Swagger UI 中：

1. 点击右上角的 "Authorize" 按钮
2. 在 "Bearer" 输入框中输入 JWT Token
3. 点击 "Authorize" 确认

JWT Token 格式：`Bearer <your-jwt-token>`

### 获取 Token

通过以下接口获取 JWT Token：

-   **用户登录**: `POST /api/v1/users/login-password`
-   **用户短信登录**: `POST /api/v1/users/login-sms`
-   **管理员登录**: `POST /api/v1/admin/login`

## 🛠️ 故障排除

### 常见问题

1. **文档生成失败**

    - 检查 Swagger 注释语法是否正确
    - 确保所有引用的类型都已定义
    - 检查 HTTP 方法是否正确（必须小写）

2. **模型没有正确显示**

    - 确保结构体有正确的 `json` 标签
    - 确保包被正确解析
    - 使用 `--parseDependency --parseInternal` 参数

3. **认证测试失败**
    - 确保安全定义正确
    - 检查 JWT Token 格式是否正确
    - 确认 Token 未过期

### 调试命令

```bash
# 详细输出生成过程
swag init -g cmd/api/main.go -o docs/swagger --parseDependency --parseInternal -v

# 检查 swag 版本
swag version

# 重新安装 swag
go install github.com/swaggo/swag/cmd/swag@latest
```

## 📚 相关资源

-   [Swaggo 官方文档](https://github.com/swaggo/swag)
-   [Swagger UI 文档](https://swagger.io/tools/swagger-ui/)
-   [OpenAPI 规范](https://swagger.io/specification/)

## 🤝 贡献指南

1. 添加新接口时，请同时添加完整的 Swagger 注释
2. 确保所有参数都有合适的 `example` 标签
3. 使用中文描述，符合项目的中文化规范
4. 更新文档后，请运行 `make docs` 重新生成文档