在 Spring Boot 项目中集成 Swagger 3.0（也称为 OpenAPI 3.0）可以极大地方便我们生成 API 文档，并提供交互式的 API 接口测试。下面是一个如何在 Spring Boot 中配置和使用 Swagger 3.0 的详解步骤：

项目配置

1. 添加依赖

   首先，在 pom.xml 文件中添加 Swagger 3 的依赖：

   <dependency>  
      <groupId>org.springdoc</groupId>  
      <artifactId>springdoc-openapi-ui</artifactId>  
      <version>1.6.9</version> <!-- 检查最新版本 -->  
   </dependency>  

   如果使用 Gradle，添加以下内容到 build.gradle 文件：

   implementation 'org.springdoc:springdoc-openapi-ui:1.6.9'  

2. 创建 OpenAPI 配置类

   创建一个配置类来自定义 OpenAPI 的元数据：

   import io.swagger.v3.oas.models.OpenAPI;  
   import io.swagger.v3.oas.models.info.Info;  
   import org.springframework.context.annotation.Bean;  
   import org.springframework.context.annotation.Configuration;  
   @Configuration  
   public class OpenAPIConfig {  
      @Bean  
      public OpenAPI customOpenAPI() {  
          return new OpenAPI()  
                  .info(new Info()  
                      .title("My API Documentation")  
                      .version("1.0.0")  
                      .description("This is the API documentation for my Spring Boot application.")  
                  );  
      }  
   }  

3. 编写控制器

   在你的 Spring Boot 应用中，根据需要编写控制器，并使用 Swagger 的注解来描述接口。常用注解有 @Operation、@Parameter、@ApiResponse等：

   import org.springframework.web.bind.annotation.GetMapping;  
   import org.springframework.web.bind.annotation.RequestParam;  
   import org.springframework.web.bind.annotation.RestController;  
   import io.swagger.v3.oas.annotations.Operation;  
   import io.swagger.v3.oas.annotations.parameters.Parameter;  
   import io.swagger.v3.oas.annotations.responses.ApiResponse;  
   import io.swagger.v3.oas.annotations.responses.ApiResponses;  
   @RestController  
   public class ExampleController {  
      @Operation(summary = "Greet the user")  
      @ApiResponses(value = {  
          @ApiResponse(responseCode = "200", description = "Successful greeting"),  
          @ApiResponse(responseCode = "400", description = "Invalid user name supplied")  
      })  
      @GetMapping("/greet")  
      public String greetUser(@Parameter(description = "Name of the user to greet") @RequestParam String name) {  
          if (name == null || name.isEmpty()) {  
              return "Name must not be empty";  
          }  
          return "Hello, " + name + "!";  
      }  
   }  

启动项目并查看 Swagger UI

1. 启动应用

   启动你的 Spring Boot 应用程序。

2. 查看 API 文档

   在浏览器中打开以下 URL，查看生成的交互式 API 文档：

   http://localhost:8080/swagger-ui/index.html  

   这里 8080 是你的应用运行的默认端口，如果你自定义了端口，请根据实际情况修改。

额外定制化

• 限制访问

  可以通过 Spring Security 等方式限制 Swagger UI 的访问，只允许开发人员或特定用户组访问。

• 修改基础路径

  如果你的应用有特定的上下文路径或外部路径映射，可以在 application.properties 或 application.yml 中指定：

  springdoc.swagger-ui.path=/custom-path  

• 自定义 Swagger 页面

  Swagger UI 提供了高度的可定制性，可以通过更换主题或添加额外的元信息来调整页面。

通过这些步骤，你就可以在 Spring Boot 项目中使用 Swagger 3.0 来生成和管理 RESTful API 文档了。这样不仅提高了接口的易用性，也为开发人员之间以及开发与测试人员之间的沟通提供了便利。