若依后端系统集成 Swagger 接口文档功能

后端代码需要修改的地方：

1、admin/src/main/resources/application.yml

# Swagger配置
swagger:
  # 是否开启swagger
  enabled: true
  # 请求前缀
#  pathMapping: /dev-api
  pathMapping: /

修改 pathMapping 不加任何前缀，接口是什么就是什么

2、common/src/main/java/com/Process/common/config/RuoYiConfig.java

// 加上这个字段
    private static boolean captchaEnabled= true;

    // 加上 getter 和 setter
    public static boolean isCaptchaEnabled() {
        return captchaEnabled;
    }

    public void setCaptchaEnabled(boolean captchaEnabled) {
        RuoYiConfig.captchaEnabled = captchaEnabled;
    }

captchaEnabled 为 true   则开启登录验证码和token验证；为false则取消，方便swagger登录 调试

3、framework/src/main/java/com/Process/framework/config/ResourcesConfig.java

@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry)
    {
        /** 本地文件上传路径 */
        registry.addResourceHandler(Constants.RESOURCE_PREFIX + "/**")
                .addResourceLocations("file:" + RuoYiConfig.getProfile() + "/");

        /** swagger配置 */
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/")
                .setCacheControl(CacheControl.maxAge(5, TimeUnit.HOURS).cachePublic());

//        Swagger 自己的接口文档路径
        registry.addResourceHandler("/v3/api-docs/**")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/swagger-resources/**")
                .addResourceLocations("classpath:/META-INF/resources/");
    }

让 Swagger 能读到 "接口列表" Swagger 页面必须访问 /v3/api-docs 才能知道你项目有哪些接口。如果不放行 → Swagger 不知道你有什么接口 → 弹框报错。让 Swagger 能读到自己的配置文件 Swagger 自己需要加载分组、文档信息，走的就是这个路径。如果不放行 → Swagger 一直弹 "无法获取配置"。

4、framework/src/main/java/com/Process/framework/web/service/SysLoginService.java

/**
     * 登录验证
     *
     * @param username 用户名
     * @param password 密码
     * @param code 验证码
     * @param uuid 唯一标识
     * @return 结果
     */
    public String login(String username, String password, String code, String uuid)
    {
//        // 验证码校验
//        validateCaptcha(username, code, uuid);
        if (RuoYiConfig.isCaptchaEnabled()) {
            validateCaptcha(username, code, uuid);
        }

        // 登录前置校验
        loginPreCheck(username, password);
        // 用户验证
        Authentication authentication = null;

登录时获取 isCaptchaEnabled的值来判断是否需要 验证码校验

5、AllProcess-process/pom.xml

<dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.6.2</version>
            <scope>compile</scope>
        </dependency>

Maven 中引入依赖

@Api(tags = "数据")
@RestController
@RequestMapping("/data")
public class DataController extends BaseController
     * 获取数据
     */
    @PreAuthorize("@ss.hasPermi('process:data:query')")
    @ApiOperation("数据")
    @GetMapping("/weekStat")
    public AjaxResult getWeekStat()
    {

接口 加 Swagger 注解

只需要加 2 种注解：

1. 类上面加：@Api(tags = "XXX")
2. 每个接口方法上面加：@ApiOperation("XXX")

Controller类中写接口时，加入@Api(tags = "数据")和@ApiOperation("数据统计")

启动后端，访问 Swagger 页面

默认地址：

http://localhost:8081/swagger-ui/index.html

直接在 Swagger 里登录拿 Token（最快）

1. 打开 Swagger：http://localhost:8081/swagger-ui/index.html

2. 找到 登录接口 ：/login

3. 点 Try it out

4. 填入你的用户名密码，例如： json

   {
     "username": "admin",
     "password": "admin123"
   }

5. 执行，返回结果里就有： json

   "token": "eyJhbGciOiJIUzI1NiJ9......."

拿到 token 后怎么用

回到 Swagger 页面右上角：Authorize → 输入：

plaintext

Bearer 你复制的token

点 Authorize 确认，之后所有接口就能正常调了。

为什么明明关了验证码还不行？

若依的底层逻辑坑：captchaEnabled: false 配置有时候不会热生效 ，或者验证码校验代码写死了强制校验字段，就算开关关了，只要后端实体类接收到code/uuid，就依然会走校验。另外还有 2 个隐藏坑：

1. 后端配置修改后没有真正完整重启服务，旧配置还在运行
2. 浏览器缓存、Swagger 缓存了旧接口定义

---

✅ 立刻生效 分步解决

1. 强制彻底重启后端

1. IDE 里完全停止当前 SpringBoot 项目
2. 清理缓存：点击 Maven → clean → compile
3. 重新启动项目，等待完全启动成功

2. 浏览器强制刷新 Swagger 页面

打开 Swagger 页面后，按快捷键 Ctrl + Shift + R 彻底强制清除缓存刷新

改完之后效果

1. 配置 captchaEnabled: false → 不校验验证码，Swagger / 前端登录都不需要
2. 配置 captchaEnabled: true → 正常校验验证码，和原来完全一样
3. 前端完全不受影响！
4. Swagger 终于可以正常登录！