SpringBoot整合Swagger UI 用于提供接口可视化界面

目录

一、引入相关依赖

二、添加配置文件

三、测试

四、Swagger 相关注解

一、引入相关依赖

1. 图像化依赖
   Swagger UI 用于提供可视化界面：

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger-ui</artifactId>
       <version>2.9.2</version>
   </dependency>
   

2. Swagger2依赖
   Swagger2 用于生成和展示接口文档：

   <dependency>
       <groupId>io.springfox</groupId>
       <artifactId>springfox-swagger2</artifactId>
       <version>2.9.2</version>
   </dependency>
   

   注意： 使用 Spring Boot 时，确保版本合适，否则可能无法成功导入。推荐的 Spring Boot 版本通常为 2.3.x 或 2.4.x。

二、添加配置文件

1. Swagger 配置类：

   在 Spring Boot 项目中，创建一个 Swagger 配置类来启用 Swagger 功能并进行相关配置。
   

   @Configuration
   @EnableSwagger2
   public class SwaggerConfig implements WebMvcConfigurer {
   
       @Bean
       public Docket createRestApi() {
           return new Docket(DocumentationType.SWAGGER_2)
                   // 添加 API 详情信息
                   .apiInfo(apiInfo())
                   .select()
                   // 只显示有 @ApiOperation 注解的接口
                   .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                   // 设置展示的路径
                   .paths(PathSelectors.any())
                   .build()
                   // 是否开启 Swagger
                   .enable(true);
       }
   
       /**
        * 设置 API 信息
        * @return ApiInfo
        */
       private ApiInfo apiInfo() {
           return new ApiInfoBuilder()
                   .title("API文档") // 文档标题
                   .description("接口文档详情信息") // 文档描述
                   .version("1.0") // 版本
                   .contact(new Contact("", "", "")) // 联系方式
                   .license("") // 许可
                   .licenseUrl("") // 许可链接
                   .build();
       }
   
       @Override
       public void addResourceHandlers(ResourceHandlerRegistry registry) {
           registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
           registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
           registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
           WebMvcConfigurer.super.addResourceHandlers(registry);
       }
   }
   

2. 说明：

   • @EnableSwagger2：启用 Swagger2 支持。
   • Docket：用于配置 Swagger。
   • @ApiOperation：控制哪些方法会被生成文档。
   • @Api：控制哪个类会被生成文档。
   • @ApiInfo：文档的元数据配置，如标题、描述、版本等。

三、测试

• 接口文档的访问地址：
  访问 Swagger UI 页面，可以查看和测试接口。默认路径为：

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

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

四、Swagger 相关注解

1. @Api
   用于标注控制器类，描述整个类的功能。
   

   @Api(tags = {"用户信息接口"})
   public class UserController {
       // 类中的方法
   }
   

2. @ApiOperation
   用于标注方法，描述该接口的功能。

3. 

   @ApiOperation(value = "查询所有用户信息")
   @GetMapping("/users")
   public List<User> getAllUsers() {
       // 查询所有用户信息
   }
   

   注： @Api 和 @ApiOperation 需要同时使用。

4. @ApiImplicitParams
   用于标注方法的参数信息，通常配合 @ApiImplicitParam 使用。

   @ApiImplicitParams({
       @ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "Long", paramType = "query")
   })
   @GetMapping("/user")
   public User getUserById(@RequestParam Long userId) {
       // 查询用户信息
   }
   

5. @ApiModel
   用于描述模型类的元数据。当用户的入参是实体类时，使用该注解描述实体类的结构。

   @ApiModel("用户类实体信息")
   public class User {
       @ApiModelProperty(value = "用户ID", required = true)
       private Long userId;
       @ApiModelProperty(value = "用户名")
       private String userName;
       // 省略其他字段和方法
   }
   

通过以上步骤配置和注解，您就可以在 Spring Boot 项目中使用 Swagger 生成接口文档并通过 Swagger UI 进行展示和交互了。这对于开发、调试和文档管理都非常有帮助。