使用经典JarLauncher运行时Swagger UI不显示接口的问题排查

针对你遇到的问题——升级Spring Boot到3.3.x并切换经典JarLauncher后Swagger UI无接口显示、/v3/api-docs返回空结构，且其他运行方式正常的情况，可尝试以下排查和解决步骤：

1. 升级springdoc版本适配Spring Boot 3.3.x #

当前使用的org.springdoc:2.6.0可能与Spring Boot 3.3.x存在兼容性差异。建议升级到springdoc官方推荐的适配版本（如2.5.0，需确保版本匹配），调整Maven依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

2. 修正控制器注解拼写错误 #

你的控制器代码中@validated为小写，正确的Spring验证注解应为@Validated（首字母大写）。虽然其他运行方式未受影响，但经典JarLauncher的类加载逻辑可能因无效注解导致控制器无法被springdoc正确识别：

@RestController
@Validated // 修正为大写V
@RequestMapping("/api/v1")
public class MyController {
    // ...
}

3. 确认经典JarLauncher打包配置与类结构 #

切换为经典JarLauncher后，需验证Maven打包是否正确包含控制器类：

• 确保spring-boot-maven-plugin的layout配置为JAR：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <layout>JAR</layout>
    </configuration>
</plugin>

• 解压打包后的Jar包，检查BOOT-INF/classes目录下是否存在你的控制器类文件，避免打包时遗漏。

4. 强化springdoc扫描配置 #

在配置文件中同时指定扫描包和路径匹配规则，消除类加载差异带来的扫描遗漏：

springdoc:
  packages-to-scan: com.yourproject.controller # 替换为控制器实际所在包
  paths-to-match: /api/v1/**

5. 排查依赖冲突 #

经典JarLauncher的类加载逻辑与分层Jar不同，执行mvn dependency:tree查看io.swagger.core.v3相关依赖，排除多版本冲突，确保swagger-core版本与springdoc版本兼容（如springdoc 2.5.0对应swagger-core 2.2.15及以上）。

6. 添加Swagger注解强制识别接口 #

给控制器和方法添加Swagger核心注解，强制springdoc识别接口定义：

@RestController
@Validated
@RequestMapping("/api/v1")
@Tag(name = "测试接口", description = "API v1版本测试接口")
public class MyController {

    @GetMapping(value="/my-endpoint")
    @Operation(summary = "获取端点数据", description = "返回测试端点信息")
    @ApiResponse(responseCode = "200", description = "请求成功")
    public Object getEndpoint(){
        // 业务逻辑
        return new Object();
    }
}

内容的提问来源于stack exchange，提问作者sarmahdi