team/tyapi-server

Fork 0

Files

liangzai 807004f78d 基础架构

2025-07-13 16:36:20 +08:00

5.6 KiB

Raw Blame History

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 接口

在 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实现
}

为 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:"张三"`
}

重新生成文档：

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 中：

点击右上角的 "Authorize" 按钮
在 "Bearer" 输入框中输入 JWT Token
点击 "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

🛠️ 故障排除

常见问题

文档生成失败
- 检查 Swagger 注释语法是否正确
- 确保所有引用的类型都已定义
- 检查 HTTP 方法是否正确（必须小写）
模型没有正确显示
- 确保结构体有正确的 json 标签
- 确保包被正确解析
- 使用 --parseDependency --parseInternal 参数
认证测试失败
- 确保安全定义正确
- 检查 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

📚 相关资源

🤝 贡献指南

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

5.6 KiB Raw Blame History Unescape Escape