172 lines
4.7 KiB
Markdown
172 lines
4.7 KiB
Markdown
# Swagger API 文档使用说明
|
||
|
||
## 📖 概述
|
||
|
||
本项目已集成 Swagger/OpenAPI 3.0，提供交互式的 API 文档界面，方便开发者和测试人员查看和测试 API 接口。
|
||
|
||
## 🚀 访问地址
|
||
|
||
启动应用后，可以通过以下地址访问 Swagger 文档：
|
||
|
||
- **Swagger UI 界面**: http://localhost:8080/swagger-ui.html
|
||
- **OpenAPI JSON**: http://localhost:8080/api-docs
|
||
- **OpenAPI YAML**: http://localhost:8080/api-docs.yaml
|
||
|
||
## 📋 功能特性
|
||
|
||
### 1. 交互式文档
|
||
- 在线查看所有 API 接口
|
||
- 直接在浏览器中测试接口
|
||
- 支持请求参数验证
|
||
- 实时查看响应结果
|
||
|
||
### 2. 接口分组
|
||
- **管理员账户管理**: `/api/admin/accounts` 相关接口
|
||
- **用户账户管理**: `/api/users` 相关接口
|
||
|
||
### 3. 详细文档
|
||
- 接口描述和用途说明
|
||
- 请求参数详细说明
|
||
- 响应数据结构
|
||
- 错误码说明
|
||
|
||
## 🔧 配置说明
|
||
|
||
### 配置文件
|
||
```yaml
|
||
# application.yml
|
||
springdoc:
|
||
api-docs:
|
||
path: /api-docs
|
||
swagger-ui:
|
||
path: /swagger-ui.html
|
||
tags-sorter: alpha
|
||
operations-sorter: alpha
|
||
doc-expansion: none
|
||
disable-swagger-default-url: true
|
||
display-request-duration: true
|
||
packages-to-scan: com.gameplatform.server.controller
|
||
```
|
||
|
||
### 配置参数说明
|
||
- `tags-sorter: alpha`: 按字母顺序排序标签
|
||
- `operations-sorter: alpha`: 按字母顺序排序操作
|
||
- `doc-expansion: none`: 默认折叠所有接口
|
||
- `display-request-duration: true`: 显示请求耗时
|
||
|
||
## 📝 使用示例
|
||
|
||
### 1. 查看接口列表
|
||
1. 打开 http://localhost:8080/swagger-ui.html
|
||
2. 选择对应的接口分组（如"管理员账户管理"）
|
||
3. 展开需要查看的接口
|
||
|
||
### 2. 测试接口
|
||
1. 点击接口右侧的"Try it out"按钮
|
||
2. 填写请求参数
|
||
3. 点击"Execute"执行请求
|
||
4. 查看响应结果
|
||
|
||
### 3. 复制接口信息
|
||
每个接口都提供了以下信息：
|
||
- **cURL 命令**: 可直接复制到终端执行
|
||
- **请求 URL**: 完整的请求地址
|
||
- **请求头**: 包含认证信息等
|
||
- **请求体**: JSON 格式的请求数据
|
||
- **响应示例**: 成功和失败的响应示例
|
||
|
||
## 🔐 认证说明
|
||
|
||
### Bearer Token 认证
|
||
对于需要认证的接口，在 Swagger UI 中：
|
||
1. 点击右上角的"Authorize"按钮
|
||
2. 在 "Value" 字段中输入 JWT Token
|
||
3. 格式：`Bearer your-jwt-token`
|
||
4. 点击"Authorize"确认
|
||
|
||
### 获取 Token
|
||
1. 使用登录接口获取 JWT Token
|
||
2. 复制响应中的 `accessToken` 字段
|
||
3. 在 Swagger UI 中配置认证
|
||
|
||
## 📊 接口文档结构
|
||
|
||
### 管理员账户管理接口
|
||
```
|
||
POST /api/admin/accounts # 创建账户
|
||
GET /api/admin/accounts # 获取账户列表
|
||
GET /api/admin/accounts/{id} # 获取账户详情
|
||
PATCH /api/admin/accounts/{id} # 更新账户
|
||
POST /api/admin/accounts/{id}/enable # 启用账户
|
||
POST /api/admin/accounts/{id}/disable # 禁用账户
|
||
POST /api/admin/accounts/{id}/reset-password # 重置密码
|
||
```
|
||
|
||
### 用户账户管理接口
|
||
```
|
||
POST /api/users # 创建用户
|
||
GET /api/users # 获取用户列表
|
||
GET /api/users/{id} # 获取用户详情
|
||
PUT /api/users/{id} # 更新用户
|
||
POST /api/users/{id}/enable # 启用用户
|
||
POST /api/users/{id}/disable # 禁用用户
|
||
```
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 开发阶段
|
||
- 使用 Swagger UI 快速测试接口
|
||
- 验证请求参数和响应格式
|
||
- 调试认证和权限问题
|
||
|
||
### 2. 测试阶段
|
||
- 导出 OpenAPI 规范文件
|
||
- 使用 Postman 等工具导入接口
|
||
- 编写自动化测试用例
|
||
|
||
### 3. 文档维护
|
||
- 及时更新接口描述
|
||
- 添加详细的参数说明
|
||
- 提供完整的示例数据
|
||
|
||
## 🔧 自定义配置
|
||
|
||
### 添加新的接口分组
|
||
```java
|
||
@Tag(name = "新功能模块", description = "新功能模块的接口说明")
|
||
@RestController
|
||
@RequestMapping("/api/new-feature")
|
||
public class NewFeatureController {
|
||
// 接口实现
|
||
}
|
||
```
|
||
|
||
### 自定义接口描述
|
||
```java
|
||
@Operation(summary = "接口标题", description = "详细的接口描述")
|
||
@Parameter(description = "参数说明")
|
||
public ResponseEntity<?> methodName(@RequestParam String param) {
|
||
// 实现逻辑
|
||
}
|
||
```
|
||
|
||
## 📚 相关资源
|
||
|
||
- [OpenAPI 3.0 规范](https://swagger.io/specification/)
|
||
- [SpringDoc 官方文档](https://springdoc.org/)
|
||
- [Swagger UI 配置选项](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)
|
||
|
||
## 🆘 常见问题
|
||
|
||
### Q: 无法访问 Swagger UI
|
||
A: 检查应用是否正常启动，确认端口 8080 未被占用
|
||
|
||
### Q: 接口显示不完整
|
||
A: 确认控制器类在 `com.gameplatform.server.controller` 包下
|
||
|
||
### Q: 认证失败
|
||
A: 检查 JWT Token 是否有效，格式是否正确
|
||
|
||
### Q: 参数验证失败
|
||
A: 查看接口文档中的参数要求，确保数据格式正确
|