在spring boot项目中整合swagger的核心步骤包括：引入依赖、配置docket bean、添加注解以实现api文档化，并可通过安全认证和隐藏接口等进一步优化。1. 引入maven依赖，推荐使用springfox-boot-starter 3.0.0版本；2. 创建配置类swaggerconfig，定义docket bean并设置api基本信息、扫描路径和包；3. 启动应用后访问/swagger-ui/index.html查看文档界面；4. 添加securityschemes和securitycontexts以支持jwt认证；5. 使用@apiignore注解或paths()方法隐藏特定api；6. 遇到问题时检查版本兼容性、路径配置及依赖冲突，确保正确启用@enableopenapi注解。
在Spring Boot项目里整合Swagger，说白了就是为了把我们那些散落在代码里的API接口，用一种清晰、交互性强的方式展现出来。核心操作其实就那么几步：引入依赖、配置一个Docket Bean，然后通过注解告诉Swagger哪些接口需要被文档化。这玩意儿一旦配好，你就能在浏览器里直接看到所有接口，还能在线调试，对前后端联调的效率提升，那可不是一星半点。我个人觉得，这几乎是现代微服务开发里不可或缺的一环，能省下大量沟通成本。
解决方案
通常，我开始一个新项目时，第一步就是把Swagger的依赖加进去。这就像给你的API文档找个好管家，省心。
1. 引入Maven依赖
如果你用的是Maven，在pom.xml里添加：
io.springfox springfox-boot-starter 3.0.0
这里我推荐使用springfox-boot-starter 3.0.0版本，它基于OpenAPI 3规范，相对老旧的Swagger2来说，功能更完善，也更符合当前趋势。当然，如果你的项目比较老，还在用Spring Boot 1.x或者Spring Cloud Finchley之类的，可能得退回到springfox-swagger2和springfox-swagger-ui的2.x版本，那时候配置起来稍微有点不一样，但核心思想是通的。
2. 创建Swagger配置类
接下来，你需要创建一个配置类来告诉Spring Boot如何初始化Swagger。我一般会命名为SwaggerConfig。
import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.oas.annotations.EnableOpenApi; // 对应Springfox 3.0.0import springfox.documentation.service.ApiInfo;import springfox.documentation.service.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;@Configuration@EnableOpenApi // 启用OpenAPI支持，如果是Springfox 2.x，这里是@EnableSwagger2public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) // 指定API文档类型为OpenAPI 3.0 .apiInfo(apiInfo()) // 设置API基本信息 .select() // 选择要生成文档的API .apis(RequestHandlerSelectors.basePackage("com.yourcompany.project.controller")) // 指定扫描的包 // .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) // 或者扫描带有@RestController注解的类 .paths(PathSelectors.any()) // 扫描所有路径 // .paths(PathSelectors.regex("/api/.*")) // 或者只扫描/api/开头的路径 .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("你的项目API文档") // 文档标题 .description("这是一个关于XXXX项目的API接口文档，希望能帮助你快速理解和使用接口。") // 详细描述 .contact(new Contact("你的名字", "http://yourwebsite.com", "your.email@example.com")) // 维护者信息 .version("1.0") // API版本 .build(); }}
这里面最关键的就是那个Docket Bean。DocumentationType.OAS_30表示我们用的是OpenAPI 3规范。apiInfo()方法就是用来配置文档的标题、描述、联系方式和版本号这些元数据。select()方法是重点，它定义了哪些API会被Swagger扫描并生成文档。我通常用RequestHandlerSelectors.basePackage()来指定控制器所在的包，这样比较精确。当然，你也可以用withClassAnnotation(RestController.class)来扫描所有带有@RestController注解的类，或者用PathSelectors.regex()来过滤特定的URL路径。
3. 访问Swagger UI
配置完成后，启动你的Spring Boot应用。然后，在浏览器中访问：http://localhost:8080/swagger-ui/index.html (如果你用的是Springfox 3.0.0)。如果是Springfox 2.x版本，通常是http://localhost:8080/swagger-ui.html。
你就能看到一个漂亮的交互式API文档界面了。
如何为Swagger文档添加安全认证（如JWT Token）？
说实话，大部分实际项目里，API都是需要认证的，比如用JWT Token。如果Swagger文档不能模拟这个认证过程，那在线调试的功能就大打折扣了。所以，给Swagger加上安全认证支持，这几乎是必做项。
我们可以在Docket配置中添加securitySchemes和securityContexts。
import java.util.Collections;import java.util.List;import springfox.documentation.service.ApiKey;import springfox.documentation.service.AuthorizationScope;import springfox.documentation.service.SecurityReference;import springfox.documentation.spi.service.contexts.SecurityContext;// ... 其他import和类定义不变 ...@Configuration@EnableOpenApipublic class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.yourcompany.project.controller")) .paths(PathSelectors.any()) .build() .securitySchemes(securitySchemes()) // 添加安全方案 .securityContexts(securityContexts()); // 添加安全上下文 } private List securitySchemes() { // 配置JWT认证方式：在请求头中传递Token return Collections.singletonList(new ApiKey("Authorization", "Authorization", "header")); } private List securityContexts() { return Collections.singletonList( SecurityContext.builder() .securityReferences(defaultAuth()) .forPaths(PathSelectors.regex("/.*")) // 对所有路径都生效 .build() ); } private List defaultAuth() { AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; return Collections.singletonList(new SecurityReference("Authorization", authorizationScopes)); } // ... apiInfo() 方法不变 ...}
这里我做了几件事：
securitySchemes(): 定义了一个名为Authorization的ApiKey，告诉Swagger，有一个认证方式叫Authorization，它会从请求的header中获取值，这个值的键也是Authorization（通常是Bearer your_token这种形式）。securityContexts(): 这是一个列表，每个SecurityContext定义了哪些API路径需要应用哪些安全方案。forPaths(PathSelectors.regex("/.*"))表示所有路径都应用这个安全方案。defaultAuth(): 定义了AuthorizationScope，这里我简单地给了个global范围，表示可以访问所有资源。
配置好后，你会发现Swagger UI界面上多了一个“Authorize”按钮。点击它，输入你的JWT Token（通常是Bearer开头），然后你再调试接口时，请求头里就会自动带上这个Token了。这真的太方便了，省去了每次手动复制粘贴Token的麻烦。
如何定制Swagger UI界面或隐藏特定API？
有时候，我们不希望所有的API都暴露在Swagger文档里，或者想让UI界面看起来更符合品牌风格。这些需求，Swagger也考虑到了。
1. 隐藏特定API
最简单粗暴的方法是使用@ApiIgnore注解。如果你有一个控制器或者一个方法，你压根不想让它出现在文档里，直接在类或方法上加上@ApiIgnore就行。
import springfox.documentation.annotations.ApiIgnore;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.RestController;@RestController@ApiIgnore // 整个控制器都不会出现在文档中public class InternalController { @GetMapping("/internal/data") public String getInternalData() { return "Sensitive internal data"; }}@RestControllerpublic class PublicController { @GetMapping("/public/info") public String getPublicInfo() { return "Public information"; } @ApiIgnore // 这个方法不会出现在文档中 @GetMapping("/public/hidden-method") public String getHiddenMethod() { return "This method is hidden."; }}
另一种方法是，在Docket配置中通过paths()进行更细粒度的控制，比如只暴露/api/v1/开头的接口：
// ... Docket 配置中 ....paths(PathSelectors.regex("/api/v1/.*")) // 只显示/api/v1/开头的路径// .paths(PathSelectors.ant("/api/v1/**")) // 也可以用ant风格的路径匹配.build();
这样，那些不符合规则的接口就不会出现在文档里了。
2. 定制Swagger UI
Springfox 3.0.0默认的UI路径是/swagger-ui/index.html。如果你想修改这个路径，或者进行一些UI上的简单定制，可以通过application.properties或application.yml来配置。
# application.propertiesspringdoc.swagger-ui.path=/docsspringdoc.api-docs.path=/api-docs # 改变原始API JSON的路径
这里我用了springdoc的配置，因为Springfox 3.0.0在内部实际上是基于springdoc-openapi的。通过springdoc.swagger-ui.path，你可以把访问路径改成http://localhost:8080/docs。
如果你想更深入地定制UI，比如修改样式、添加Logo，那就得稍微麻烦一点了。你需要下载Swagger UI的静态资源，然后放到Spring Boot的src/main/resources/static目录下，覆盖掉默认的资源文件。这通常涉及到修改index.html，引入自定义的CSS或JS文件。我个人觉得，除非有非常强的品牌要求，否则默认的UI已经足够用了，没必要折腾太多。毕竟，我们的主要目标是API文档的可用性，而不是UI有多花哨。
集成Swagger时常见的坑与解决方案？
在我自己的项目实践中，集成Swagger虽然总体顺利，但也遇到过一些让人头疼的小问题。
1. 版本冲突或不兼容
这是最常见的问题。比如，你用了Spring Boot 2.6.x，却引入了老旧的Springfox 2.x版本，或者Springfox 3.0.0和某些Spring Cloud版本之间会有依赖冲突。
症状： 应用启动失败，报错信息通常是NoClassDefFoundError、NoSuchMethodError或者Bean创建失败。Swagger UI无法访问，或者显示空白。
解决方案：
检查Spring Boot和Springfox版本兼容性。 Springfox 3.0.0通常与Spring Boot 2.x系列（尤其是2.3.x及以上）配合较好。如果遇到问题，可以尝试升级或降级Spring Boot版本，或者调整Springfox的版本。
排除传递性依赖。 有时，其他库会引入旧版本的Swagger依赖。你可以在pom.xml中使用标签来排除它们。例如：
io.springfox springfox-boot-starter 3.0.0 io.swagger swagger-models
清理Maven/Gradle缓存。 mvn clean install 或 gradle clean build 后，删除本地Maven仓库中相关的Springfox/Swagger目录，再重新构建。
2. Swagger UI无法访问或No handler found
你启动了应用，但访问/swagger-ui/index.html或/swagger-ui.html时却出现404错误。
症状： 浏览器显示404，或者控制台报错No handler found for GET /swagger-ui.html。解决方案：检查@EnableOpenApi或@EnableSwagger2注解是否已添加。 这是启用Swagger的关键。确认你的Spring Boot版本。 Spring Boot 2.6.0及以上版本默认禁用了路径匹配策略，这可能会影响Swagger UI的访问。你需要在application.properties中添加：
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
或者，如果你用的是Springfox 3.0.0，并且Spring Boot版本较高，可以尝试使用springdoc-openapi-ui替代springfox-boot-starter，它对新版Spring Boot的兼容性更好。
检查端口和上下文路径。 确保你访问的localhost:8080是正确的，如果你的应用有上下文路径（比如/my-app），那么完整路径应该是http://localhost:8080/my-app/swagger-ui/index.html。
3. API文档内容不全或显示异常
你发现有些控制器或方法没有出现在文档中，或者参数、返回值显示不正确。
症状： 某些API缺失，或者参数类型、描述与实际不符。解决方案：检查Docket的select()配置。 确保basePackage、apis、paths等配置正确地覆盖了你的API。是不是包名写错了？是不是路径匹配规则太严格了？检查API注解。 确保你的控制器和方法使用了正确的Spring MVC注解（@RestController, @GetMapping, @PostMapping等），以及Swagger相关的注解（@Api, @ApiOperation, @ApiParam, @ApiModelProperty等）。自定义类型解析器。 对于一些复杂或自定义的Java类型，Swagger可能无法正确解析。你可能需要实现AlternateTypeRule来自定义它们的显示方式。这个就比较高级了，通常在遇到特殊情况时才需要。
总的来说，Swagger的集成过程相对成熟，大部分问题都集中在版本兼容性和路径配置上。只要细心检查配置和依赖，通常都能顺利解决。
以上就是Spring Boot整合Swagger详细配置教程的详细内容，更多请关注创想鸟其它相关文章！
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如发现本站有涉嫌抄袭侵权/违法违规的内容， 请发送邮件至 chuangxiangniao@163.com 举报，一经查实，本站将立刻删除。
发布者：程序猿，转转请注明出处：https://www.chuangxiangniao.com/p/137848.html
微信扫一扫 
支付宝扫一扫 
