Fitten Code接口文档生成：基于已有代码快速输出Swagger注释

在Spring Boot项目中集成Swagger文档，已经成为团队协作和接口调试的标配。操作本身并不复杂，但有几个细节容易忽略——比如依赖版本没选对，或者注解遗漏导致接口页面空白。下面顺着完整流程走一遍，从依赖配置到页面验证，每一步都做到位。

需要额外说明一点：这里所有的操作都是在不改动业务逻辑的前提下进行的，只给Controller接口补上Swagger 3（Springdoc OpenAPI）注释，最终生成一个可交互的API文档页面。

确认项目已集成Springdoc OpenAPI依赖

先打开项目的 pom.xml 文件，检查里面有没有

这个依赖。如果找不到，那就手动补上：

org.springdoc
springdoc-openapi-starter-webmvc-ui
2.3.0

版本号一定得 ≥ 2.0.0，低于这个版本的话，@Operation 和 @Parameter 这些新注解根本识别不了。还需要注意的是，旧版的 springfox 和 springdoc 不能共存，否则应用启动就会直接报错。

为Controller类添加基础API分组信息

在目标 Controller 类上方添加 @Tag 注解，指定一个中文标签名和描述：

@Tag(name = "用户管理", description = "注册、登录、信息查询等用户相关接口")

这一步不能省略。没有 @Tag 的 Controller，在 Swagger UI 里会归入默认的 Default 分组，而且不显示中文标题——接口一多起来，前端同事查阅体验会非常难受。

逐个方法补全Swagger注释

对于每个 @GetMapping、@PostMapping 之类的映射方法，需要按顺序做好三件事。

：在方法签名上方添加 @Operation，summary 是必填项，description 可以选填：

@Operation(summary = "根据ID查询用户详情", description = "传入合法用户ID，返回完整用户信息，包含头像URL和注册时间")

：给每个路径变量、查询参数、请求体标注语义化说明。路径变量用 @PathVariable 配合 @Parameter(description = "...")；查询参数用 @RequestParam 加上 @Parameter(description = "...")；请求体对象前加 @io.swagger.v3.oas.annotations.media.Schema(description = "...")，并在其字段上使用 @Schema(description = "...")。

：明确声明成功响应体的结构和HTTP状态码：

@ApiResponse(responseCode = "200", description = "查询成功", content = @Content(schema = @Schema(implementation = UserVO.class)))

如果这个方法可能抛出全局异常（比如 UserNotFoundException），一定要额外补充对应的 @ApiResponse，否则在 Swagger UI 里根本看不到那个错误码分支。

验证文档是否生效

启动应用后，在浏览器里访问 http://localhost:8080/swagger-ui/index.html。

如果页面空白或者提示 404，先检查一下是不是误用了旧版路径 /swagger-ui.html。Springdoc 2.x 的默认路径就是 /swagger-ui/index.html。

假如页面正常加载了但一个接口都没显示，那说明至少有一个 Controller 缺少 @Tag，或者某个方法缺少 @Operation。回头逐个排查就好。