Spring Boot集成Swagger/OpenAPI需三步：引入对应版本依赖（2.x用springfox-swagger2，3.x用springfox-boot-starter）、编写配置类（启用@EnableOpenApi并指定扫描包与API信息）、添加@Api等注解补充接口语义；开发环境可配swagger.enabled控制开关，文档默认访问/swagger-ui/index.html。
在 Spring Boot 项目中集成 Swagger（或 OpenAPI）生成在线接口文档，核心是三步：引入依赖、配置类、加注解。关键不在于写多少代码，而在于选对版本、配对路径、控制环境开关。
选对依赖和版本
Spring Boot 2.x 推荐两种主流方案：
-
Swagger2（OpenAPI 2.0 规范）：用
springfox-swagger2+springfox-swagger-ui，版本建议 2.9.2 或 2.8.0（稳定兼容）； -
OpenAPI 3（现代标准）：用
springfox-boot-starter（3.0.0+），它内置 OpenAPI 3 支持，不再需要单独引入 UI 依赖，且配置更简洁。
注意：SpringFox 2.x 和 3.x 配置方式不同——2.x 用 @EnableSwagger2 和 DocumentationType.SWAGGER_2；3.x 用 @EnableOpenApi 和 DocumentationType.OAS_30，别混用。
写一个基础配置类
配置类负责告诉 Swagger 扫哪些包、显示什么信息、是否启用。以 OpenAPI 3 为例：
立即学习“Java免费学习笔记（深入）”；
@Configuration
@EnableOpenApi
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 替换为你自己的 controller 包名
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("用户服务 API 文档")
.description("提供用户注册、登录、查询等 REST 接口")
.version("v1.0")
.contact(new Contact("开发组", "https://example.com", "dev@example.com"))
.build();
}
}
如果只想在开发环境启用，可在配置类中注入 @Value("${swagger.enabled:true}")，再传给 .enable(enable)。
用注解补充接口语义
光有自动扫描还不够，需少量注解让文档更清晰：
-
@Api加在 Controller 类上，说明模块用途； -
@ApiOperation加在每个接口方法上，描述功能； -
@ApiParam加在参数上（尤其@RequestParam或@PathVariable），说明含义和是否必填； -
@ApiModel+@ApiModelProperty加在 DTO 实体类上，解释字段作用。
例如：@ApiOperation("根据ID查询用户") 比方法名 getUserById 更直观；@ApiParam(value = "用户唯一标识", required = true) 能让前端一眼看清参数约束。
访问和验证文档
启动项目后，默认访问地址为：
- Swagger2：http://localhost:8080/swagger-ui.html
- OpenAPI 3（springfox-boot-starter）：http://localhost:8080/swagger-ui/index.html
打开页面即可看到分组接口列表、参数表单、响应示例，还能直接点击“Try it out”发起真实请求测试。若页面 404，请检查是否遗漏 springfox-swagger-ui 依赖（Swagger2）或确认静态资源路径未被拦截（如 Spring Security 需放行 /swagger-ui/** 和 /webjars/**）。
