tyapi-server/docs/swagger

TYAPI Server Swagger 文档

📖 概述

本项目使用 Swaggo 自动生成 Swagger/OpenAPI 文档，提供完整的 API 接口文档和在线测试功能。

🚀 快速开始

1. 启动服务器

# 开发模式启动
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

📝 文档更新

自动更新

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

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

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

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

手动更新

# 使用 Makefile
make docs

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

🔧 开发指南

添加新的 API 接口

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

// @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 结构体添加注释和示例：

// @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. 重新生成文档：

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 未过期

调试命令

# 详细输出生成过程
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 官方文档
• Swagger UI 文档
• OpenAPI 规范

🤝 贡献指南

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