4.2 KiB

Raw Blame History

Swagger UI Authorize按钮不显示问题解决方案

问题描述

在Swagger UI中，右上角没有显示"Authorize"按钮，无法配置JWT token进行API测试。

原因分析

Swagger UI版本问题：某些版本的Swagger UI可能不显示Authorize按钮
配置方式问题：gin-swagger的配置可能不完整
浏览器缓存问题：浏览器可能缓存了旧版本的页面

解决方案

方案1：使用自定义Swagger UI（推荐）

我已经创建了一个自定义的Swagger UI页面，确保Authorize按钮能正确显示：

访问自定义Swagger UI：
```
http://localhost:8080/swagger-ui
```
这个页面使用了最新版本的Swagger UI (5.9.0)，确保Authorize按钮正常显示

方案2：检查配置

确保以下配置正确：

1. main.go中的安全定义配置

// @securityDefinitions.apikey BearerAuth
// @in header
// @name Authorization
// @description 请输入 "Bearer " + JWT token，例如: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

2. API控制器中的安全配置

// @Security BearerAuth
// @Router /auth/roles [post]
func (c *RoleController) CreateRole(ctx *gin.Context) {
    // ...
}

方案3：浏览器操作

清除浏览器缓存：
- 按 Ctrl+Shift+Delete
- 选择"缓存的图片和文件"
- 点击"清除数据"
强制刷新页面：
- 按 Ctrl+F5 强制刷新
- 或者按 Ctrl+Shift+R
检查浏览器控制台：
- 按 F12 打开开发者工具
- 查看Console标签页是否有错误信息
- 查看Network标签页是否有请求失败

方案4：验证配置

运行测试脚本验证配置：

.\test-swagger-auth.ps1

这个脚本会：

检查后端服务状态
验证Swagger JSON文档
检查安全定义配置
检查API安全配置
测试Swagger UI页面

使用步骤

1. 启动后端服务

cd backend
go run main.go

2. 访问Swagger UI

默认UI：http://localhost:8080/swagger/index.html
自定义UI：http://localhost:8080/swagger-ui （推荐）

3. 配置身份验证

点击右上角的 "Authorize" 按钮
在输入框中输入：Bearer <your-jwt-token>
点击 "Authorize" 按钮

4. 获取JWT Token

先调用 /api/auth/captcha 获取验证码
再调用 /api/auth/login 进行登录
复制返回的 access_token

故障排除

如果Authorize按钮仍然不显示：

检查Swagger JSON文档：
```
http://localhost:8080/swagger/doc.json
```
确保包含 securityDefinitions 部分
检查API配置：确保需要认证的API包含 security 配置
尝试不同的浏览器：
- Chrome
- Firefox
- Edge
检查网络连接：确保能正常访问Swagger UI页面

常见错误及解决方案：

"Failed to load resource"：
- 检查后端服务是否正常运行
- 检查端口8080是否被占用
"CORS error"：
- 确保CORS中间件正确配置
- 检查请求来源
"404 Not Found"：
- 确保Swagger路由正确配置
- 检查文件路径

验证成功标志

当配置正确时，你应该能看到：

✅ Swagger UI页面正常加载
✅ 右上角显示 "Authorize" 按钮
✅ 点击Authorize按钮能打开认证对话框
✅ 需要认证的API显示锁定图标 🔒
✅ 配置token后能正常调用需要认证的API

测试API流程

获取验证码：
```
GET /api/auth/captcha
```

用户登录：

POST /api/auth/login
{
  "username": "admin",
  "password": "admin123",
  "captcha": "验证码",
  "captcha_id": "验证码ID"
}

配置Authorize：
- 点击Authorize按钮
- 输入：Bearer <access_token>
- 点击Authorize

测试需要认证的API：

GET /api/auth/roles
POST /api/auth/roles
PUT /api/auth/roles/{id}
DELETE /api/auth/roles/{id}

总结

如果默认的Swagger UI不显示Authorize按钮，请使用自定义的Swagger UI页面：

http://localhost:8080/swagger-ui

这个页面使用了最新版本的Swagger UI，确保Authorize按钮能正常显示和使用。

4.2 KiB Raw Blame History