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配置示例：

   <dependency>
       <groupId>org.springdoc</groupId>
       <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
       <version>2.0.2</version>
   </dependency>
   

   
   如果你使用的是Gradle，可以在build.gradle文件中添加以下依赖：

   implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
   

2. 配置应用属性：
   在application.properties或application.yml文件中添加Swagger的相关配置。例如：

   # application.properties
   springdoc.api-docs.path=/v3/api-docs
   springdoc.swagger-ui.path=/swagger-ui.html
   

   
   或者在application.yml中：

   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，代码如下：

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的依赖：

<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，代码如下：

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文档的信息。例如：

# 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中：

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文件中添加以下配置：

# application.properties
springdoc.swagger-ui.theme=theme-light
springdoc.swagger-ui.layout=StandaloneLayout
springdoc.swagger-ui.css=/css/custom.css

或者在application.yml中：

springdoc:
  swagger-ui:
    theme: theme-light
    layout: StandaloneLayout
    css: /css/custom.css

在src/main/resources/static/css目录下创建一个custom.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界面。希望本文的指导能帮助你在项目中顺利实现这一目标。