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 {@Beanpublic 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();}@Overridepublic 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 进行展示和交互了。这对于开发、调试和文档管理都非常有帮助。