Spring Boot 集成 Swagger 3 进阶指南【避坑指南】
2024-01-07 18:30:30
进阶指南：集成 Swagger 3 避坑策略
简介
在当今飞速发展的技术时代，Swagger 3 已成为 Spring Boot 项目中集成 RESTful API 文档的利器。然而，在集成过程中，难免会遇到各种坑。本文将结合笔者的实战经验，分享一些进阶指南和避坑策略，助你顺利集成 Swagger 3。
1. 启动类添加注解开起 Swagger
在 Spring Boot 项目中，可以通过在启动类上添加 @EnableOpenApi 注解来开启 Swagger。但需要注意的是，在 Spring Boot 2.6 及以上版本中，由于引入了新的 PathPatternParser，可能会导致集成 Swagger 3 出现问题。
解决方案：集成 Swagger Java Config
为了解决上述问题，可以集成 Swagger Java Config 来配置 Swagger。具体步骤如下：
- 引入 Swagger 3 依赖。
- 创建 Java 配置类，实现
SwaggerConfiguration接口。 - 在配置类中，使用
Docket类配置 Swagger 参数，如标题、版本等。 - 在启动类中，将配置类作为参数传递给
SpringdocConfig类。
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.servers.Server;
import org.springdoc.core.SpringDocConfigProperties;
import org.springdoc.core.SpringDocConfiguration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class SwaggerConfiguration implements SwaggerConfiguration {
@Value("${server.port}")
private String port;
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info().title("API Title").version("1.0.0"))
.addServersItem(new Server().url("http://localhost:" + port));
}
@Bean
public SpringDocConfiguration springDocConfiguration() {
return new SpringDocConfiguration();
}
}
2. 添加 Path 匹配策略切换配置
如果以上方法仍然无法解决问题，可以尝试添加如下配置：
springdoc.use-springmvc-path-match: true
此配置的作用是将 Path 匹配策略切换回 Spring MVC 默认策略，解决 Swagger 3 与 Spring Boot 2.6+ 版本不兼容的问题。
3. 使用 Swagger UI
集成 Swagger 3 后，可以使用 Swagger UI 查看 API 文档。Swagger UI 是一个基于 Web 的工具，帮助开发者轻松浏览和测试 API。
4. 使用 Swagger Codegen 生成代码
Swagger Codegen 是一个根据 Swagger 定义生成代码的工具。通过 Swagger Codegen，可以轻松生成 Java、Python、C# 等多种语言的代码。
5. 其他进阶技巧
- 使用
@Operation注解详细操作。 - 使用
@RequestBody和@ResponseBody注解请求和响应体。 - 使用
@ApiResponse注解描述响应状态码。 - 使用
@ApiParam注解描述请求参数。
总结
通过遵循上述步骤，你可以轻松集成 Swagger 3 并生成 API 文档。本文所提供的进阶指南和避坑策略将助你化解集成过程中的难题，提升开发效率和项目质量。
常见问题解答
-
集成 Swagger 3 时遇到
IllegalArgumentException: URL does not contain any path after host错误，如何解决？答：添加
springdoc.use-springmvc-path-match: true配置。 -
Swagger UI 无法显示 API 文档，如何解决？
答：检查 Swagger 配置是否正确，并确保启动类已添加
@EnableOpenApi注解。 -
如何在 Swagger UI 中生成代码片段？
答：点击 API 操作旁边的 "Code" 按钮。
-
如何使用 Swagger Codegen 生成代码？
答：安装 Swagger Codegen 并使用其命令行界面生成代码。
-
Swagger 3 与 Spring Boot 2.7 及以上版本是否兼容？
答：是的，Swagger 3 已兼容 Spring Boot 2.7 及以上版本。
