基础架构
This commit is contained in:
253
docs/swagger/README.md
Normal file
253
docs/swagger/README.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# 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` 重新生成文档
|
||||
Reference in New Issue
Block a user