254 lines
5.6 KiB
Markdown
254 lines
5.6 KiB
Markdown
# 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` 重新生成文档
|