Spring Boot 3.x与Swagger 3的整合之道：springdoc-openapi的使用指南

### 摘要 本文旨在介绍如何在Spring Boot 3.x版本中整合Swagger 3，使用的工具是springdoc-openapi。与使用springfox-swagger2不同，自Spring Boot 2.6.x版本起，Spring Boot与Swagger之间存在已知的不兼容问题，因此，如果继续使用springfox进行配置，用户在启动项目时可能会遇到错误。本文将提供解决这些问题的指导，确保Swagger UI页面能够正常访问。 ### 关键词 Spring Boot, Swagger 3, springdoc, 不兼容, UI页面 ## 一、大纲一：Spring Boot 3.x与Swagger 3的整合基础 ### 1.1 Spring Boot 3.x与Swagger 3的兼容性问题分析 随着技术的不断进步，Spring Boot 3.x 版本的发布带来了许多新的特性和优化。然而，这也意味着一些旧的依赖库可能不再兼容。特别是在集成Swagger 3时，Spring Boot 2.6.x 版本之后出现了一些已知的不兼容问题。这些问题主要集中在依赖管理和配置上，导致用户在启动项目时可能会遇到各种错误，如类找不到、依赖冲突等。 具体来说，Spring Boot 2.6.x 版本对依赖管理进行了重大调整，移除了对一些旧版本库的支持。而springfox-swagger2 作为早期常用的Swagger集成工具，其依赖库与Spring Boot 3.x 的新特性并不完全兼容。这导致了在项目启动时，springfox-swagger2 无法正确加载所需的类和资源，从而引发一系列错误。 为了解决这些兼容性问题，社区推荐使用springdoc-openapi。springdoc-openapi 是一个基于OpenAPI 3.0规范的库，它不仅支持Spring Boot 3.x，还提供了更加简洁和灵活的配置方式。通过使用springdoc-openapi，开发者可以轻松地在项目中集成Swagger 3，确保Swagger UI页面能够正常访问。 ### 1.2 springdoc-openapi的引入与配置步骤 要在Spring Boot 3.x 项目中引入并配置springdoc-openapi，可以按照以下步骤进行： 1. **添加依赖**： 在项目的`pom.xml`文件中添加springdoc-openapi的依赖。以下是Maven配置示例： ```xml <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.0.2</version> </dependency> ``` 如果你使用的是Gradle，可以在`build.gradle`文件中添加以下依赖： ```groovy implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2' ``` 2. **配置应用属性**： 在`application.properties`或`application.yml`文件中添加Swagger的相关配置。例如： ```properties # application.properties springdoc.api-docs.path=/v3/api-docs springdoc.swagger-ui.path=/swagger-ui.html ``` 或者在`application.yml`中： ```yaml springdoc: api-docs: path: /v3/api-docs swagger-ui: path: /swagger-ui.html ``` 3. **启动项目**： 完成上述配置后，启动Spring Boot项目。访问`http://localhost:8080/swagger-ui.html`，你应该能够看到Swagger UI页面，其中包含了所有已定义的API文档。 ### 1.3 Swagger配置文件详解 在Spring Boot 3.x 中使用springdoc-openapi时，可以通过多种方式对Swagger进行详细配置。以下是一些常见的配置选项及其说明： 1. **API文档路径**： - `springdoc.api-docs.path`：指定生成的API文档的路径，默认为`/v3/api-docs`。 - `springdoc.api-docs.groups`：可以用于分组API文档，适用于大型项目。 2. **Swagger UI路径**： - `springdoc.swagger-ui.path`：指定Swagger UI页面的访问路径，默认为`/swagger-ui.html`。 - `springdoc.swagger-ui.config-url`：可以指定Swagger UI的配置文件URL。 3. **安全配置**： - `springdoc.security.enabled`：启用或禁用安全配置，默认为`true`。 - `springdoc.security.schemes`：定义安全方案，如OAuth2、Basic Auth等。 4. **其他配置**： - `springdoc.info.title`：设置API文档的标题。 - `springdoc.info.description`：设置API文档的描述。 - `springdoc.info.version`：设置API文档的版本号。 通过这些配置选项，开发者可以根据项目需求灵活地定制Swagger的行为和外观。例如，可以通过设置`springdoc.info.title`和`springdoc.info.description`来提供更详细的API文档信息，使用户更容易理解和使用API。 总之，通过使用springdoc-openapi，开发者可以轻松地在Spring Boot 3.x 项目中集成Swagger 3，解决兼容性问题，并提供丰富的API文档和UI界面。希望本文的指导能帮助你在项目中顺利实现这一目标。 ## 二、大纲一：实践操作与优化 ### 2.1 创建Swagger 3的基本使用示例 在了解了Spring Boot 3.x与Swagger 3的兼容性问题及springdoc-openapi的引入与配置步骤后，接下来我们将通过一个具体的示例来展示如何在Spring Boot 3.x项目中创建并使用Swagger 3。 首先，我们需要创建一个新的Spring Boot 3.x项目。假设我们已经完成了项目的初始化，并且在`pom.xml`文件中添加了springdoc-openapi的依赖。接下来，我们将在项目中创建一个简单的REST控制器，以展示如何生成和访问Swagger文档。 #### 2.1.1 创建REST控制器 在`src/main/java/com/example/demo/controller`目录下创建一个新的Java类`UserController.java`，代码如下： ```java package com.example.demo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/users") public class UserController { @GetMapping public String getUsers() { return "Hello, Users!"; } } ``` #### 2.1.2 访问Swagger UI页面 完成上述控制器的创建后，启动Spring Boot项目。打开浏览器，访问`http://localhost:8080/swagger-ui.html`，你应该能够看到Swagger UI页面，其中包含了`/users`接口的文档。 通过这个简单的示例，我们可以看到springdoc-openapi如何自动扫描并生成API文档，使得开发者无需手动编写大量的注解和配置。这对于快速开发和测试API非常有帮助。 ### 2.2 集成Spring Security进行权限控制 在实际项目中，API的安全性是一个重要的考虑因素。Spring Security是Spring生态系统中广泛使用的安全框架，它可以与Swagger 3无缝集成，确保只有经过身份验证的用户才能访问特定的API。 #### 2.2.1 添加Spring Security依赖 在`pom.xml`文件中添加Spring Security的依赖： ```xml <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency> ``` #### 2.2.2 配置Spring Security 在`src/main/java/com/example/demo/config`目录下创建一个新的Java类`SecurityConfig.java`，代码如下： ```java package com.example.demo.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.web.SecurityFilterChain; @Configuration @EnableWebSecurity public class SecurityConfig { @Bean public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .authorizeRequests() .antMatchers("/v3/api-docs", "/swagger-ui.html", "/swagger-ui/**").permitAll() .anyRequest().authenticated() .and() .formLogin() .loginPage("/login") .permitAll() .and() .logout() .permitAll(); return http.build(); } } ``` 在这个配置中，我们允许未认证的用户访问Swagger相关的路径（`/v3/api-docs`, `/swagger-ui.html`, `/swagger-ui/**`），而其他所有请求都需要经过身份验证。 #### 2.2.3 测试权限控制 启动项目后，尝试访问`http://localhost:8080/users`，你应该会被重定向到登录页面。登录后，再次访问该路径，你应该能够看到返回的“Hello, Users!”消息。 通过这种方式，我们可以确保API的安全性，同时仍然允许未认证的用户访问Swagger UI页面，以便于开发和测试。 ### 2.3 Swagger UI页面的定制化展示 Swagger UI页面的默认样式和布局可能不完全符合项目的需求。幸运的是，springdoc-openapi提供了丰富的配置选项，允许开发者对Swagger UI页面进行定制化展示。 #### 2.3.1 自定义API文档信息 在`application.properties`或`application.yml`文件中，可以添加更多的配置项来自定义API文档的信息。例如： ```properties # application.properties springdoc.api-docs.path=/v3/api-docs springdoc.swagger-ui.path=/swagger-ui.html springdoc.info.title=My API Documentation springdoc.info.description=This is the documentation for my API. springdoc.info.version=1.0.0 ``` 或者在`application.yml`中： ```yaml springdoc: api-docs: path: /v3/api-docs swagger-ui: path: /swagger-ui.html info: title: My API Documentation description: This is the documentation for my API. version: 1.0.0 ``` 通过这些配置，我们可以为API文档提供更详细的标题、描述和版本号，使用户更容易理解和使用API。 #### 2.3.2 自定义Swagger UI样式 除了基本的文档信息外，还可以通过配置项来自定义Swagger UI的样式。例如，可以更改主题颜色、添加自定义CSS等。在`application.properties`或`application.yml`文件中添加以下配置： ```properties # application.properties springdoc.swagger-ui.theme=theme-light springdoc.swagger-ui.layout=StandaloneLayout springdoc.swagger-ui.css=/css/custom.css ``` 或者在`application.yml`中： ```yaml springdoc: swagger-ui: theme: theme-light layout: StandaloneLayout css: /css/custom.css ``` 在`src/main/resources/static/css`目录下创建一个`custom.css`文件，添加自定义的CSS样式： ```css /* custom.css */ .swagger-ui .topbar { background-color: #3f51b5; color: white; } ``` 通过这些配置，我们可以根据项目的需求对Swagger UI页面进行个性化的定制，使其更加符合用户的审美和使用习惯。 总之，通过使用springdoc-openapi，开发者不仅可以轻松地在Spring Boot 3.x项目中集成Swagger 3，解决兼容性问题，还可以通过丰富的配置选项对Swagger UI页面进行定制化展示，提供更加友好和专业的用户体验。希望本文的指导能帮助你在项目中顺利实现这一目标。 ## 三、总结 本文详细介绍了如何在Spring Boot 3.x版本中整合Swagger 3，使用的是springdoc-openapi工具。通过对比springfox-swagger2，我们指出了Spring Boot 2.6.x版本之后出现的不兼容问题，并提供了具体的解决方案。文章从依赖添加、配置文件设置到启动项目，逐步引导读者完成Swagger 3的集成。此外，我们还展示了如何通过Spring Security进行权限控制，确保API的安全性，以及如何自定义Swagger UI页面的样式和布局，以满足项目需求。通过这些步骤，开发者可以轻松地在Spring Boot 3.x项目中实现Swagger 3的集成，提供丰富且专业的API文档和UI界面。希望本文的指导能帮助你在项目中顺利实现这一目标。