game_server/docs/Swagger使用说明.md

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. 详细文档

• 接口描述和用途说明
• 请求参数详细说明
• 响应数据结构
• 错误码说明

🔧 配置说明

配置文件

# 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. 文档维护

• 及时更新接口描述
• 添加详细的参数说明
• 提供完整的示例数据

🔧 自定义配置

添加新的接口分组

@Tag(name = "新功能模块", description = "新功能模块的接口说明")
@RestController
@RequestMapping("/api/new-feature")
public class NewFeatureController {
    // 接口实现
}

自定义接口描述

@Operation(summary = "接口标题", description = "详细的接口描述")
@Parameter(description = "参数说明")
public ResponseEntity<?> methodName(@RequestParam String param) {
    // 实现逻辑
}

📚 相关资源

• OpenAPI 3.0 规范
• SpringDoc 官方文档
• Swagger UI 配置选项

🆘 常见问题

Q: 无法访问 Swagger UI

A: 检查应用是否正常启动，确认端口 8080 未被占用

Q: 接口显示不完整

A: 确认控制器类在 com.gameplatform.server.controller 包下

Q: 认证失败

A: 检查 JWT Token 是否有效，格式是否正确

Q: 参数验证失败

A: 查看接口文档中的参数要求，确保数据格式正确