SpringBoot 整合Swagger2

一、Swagger简介

Swagger是一套开源工具和规范，用于设计、构建和文档化RESTful Web服务。它允许开发人员定义API的各个方面，并生成易于理解的API文档和交互式API探索界面。同时，Swagger还提供代码生成工具，可自动生成与API交互的客户端和服务器端代码，提高开发效率。

• 官网：https://swagger.io/

二、SpringBoot集成Swagger

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

1. 新建一个SpringBoot-web项目

2. 添加Maven依赖

   <dependency>
      <groupId>io.springfoxgroupId>
      <artifactId>springfox-swagger2artifactId>
      <version>2.9.2version>
   dependency>
   
   <dependency>
      <groupId>io.springfoxgroupId>
      <artifactId>springfox-swagger-uiartifactId>
      <version>2.9.2version>
   dependency>
   

3. 编写HelloController，测试确保运行成功！

   @RestController
   public class HelloController {
   
       @RequestMapping("/hello")
       public String hello(){
           return "hello swagger";
       }
   }
   

4. 要使用Swagger，我们需要编写一个配置类SwaggerConfig来配置 Swagger

    package com.liming.config;
    
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2// 开启Swagger2的自动配置
    public class SwaggerConfig extends WebMvcConfigurationSupport {
    
        /**
         * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
         * @param registry void
         */
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
            // 解决静态资源无法访问
            registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
            // 解决swagger无法访问
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            // 解决swagger的js文件无法访问
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }
   

5. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

   

三、配置Swagger

1. Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

   @Bean //配置docket以配置Swagger具体参数
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2);
   }
   

2. 可以通过apiInfo()属性配置文档信息

    //配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题") // 标题
                .description("学习演示如何配置Swagger") //描述
                .version("v1.0") // 版本
                .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "[email protected]"))
                .build();
    }
   

3. Docket 实例关联上 apiInfo()

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
   }
   

4. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

   

四、配置扫描接口

1. 构建Docket时通过select()方法配置怎么扫描接口。

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
         .apis(RequestHandlerSelectors.basePackage("com.liming.controller"))
         .build();
   }
   

2. 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

   

3. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

   1、basePackage(final String basePackage) // 根据包路径扫描接口
   2、any() // 扫描所有，项目中的所有接口都会被扫描到
   3、none() // 不扫描接口

   4、// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
   withMethodAnnotation(final Class annotation)
   5、// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
   withClassAnnotation(final Class annotation)

4. 除此之外，我们还可以配置接口扫描过滤：

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
          // 配置如何通过path过滤,即这里只扫描请求以/user开头的接口
         .paths(PathSelectors.ant("/user/**"))
         .build();
   }
   

5. 这里的可选值还有

   any() // 任何请求都扫描
   none() // 任何请求都不扫描
   regex(final String pathRegex) // 通过正则表达式控制
   ant(final String antPattern) // 通过ant()控制

SwaggerConfig基础配置全代码

package com.liming.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.limjing.controller")) // 只扫描controller接口
                .paths(PathSelectors.any()) // 配置如何通过path过滤,即这里扫描所有请求的接口
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题") // 标题
                .description("学习演示如何配置Swagger") //描述
                .version("v1.0") // 版本
                .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "[email protected]"))
                .build();
    }

    /**
     * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
     *
     * @param registry void
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

五、配置Swagger开关

1. 通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
         .select()
         .apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller"))
         .paths(PathSelectors.ant("/ss/**"))
         .build();
   }
   

   

2. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

   @Bean
   public Docket docket(Environment environment) {
      // 设置要显示swagger的环境
      Profiles of = Profiles.of("dev", "test");
      // 判断当前是否处于该环境
      // 通过 enable() 接收此参数判断是否要显示
      boolean flag = environment.acceptsProfiles(of);
      
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .enable(flag)
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.liming.controller"))
         .paths(PathSelectors.ant("/user/**"))
         .build();
   }
   

3. 可以在项目中增加配置文件

   application.yml ->spring.profiles.active=dev
   application-dev.yml ->端口：8081
   application-pro.yml->端口：8082

   结果：pro正式环境会关闭swagger功能

六、配置API分组

1. 如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

   @Bean
   public Docket docket(Environment environment) {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
         .groupName("黎明") // 配置分组
          // 省略配置....
   }
   

2. 重启项目查看分组

   

3. 如何配置多个分组？配置多个分组只需要配置多个docket即可：

   @Bean
   public Docket docket1(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
   }
   @Bean
   public Docket docket2(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
   }
   @Bean
   public Docket docket3(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
   }
   

4. 重启项目查看即可

   

七、实体配置

1. 新建一个实体类

   //@Api("注释")
   @ApiModel("用户实体")
   public class User {
       @ApiModelProperty("用户名")
       private String username;
       @ApiModelProperty("密码")
       private String password;
   
       public String getUsername() {
           return username;
       }
   
       public void setUsername(String username) {
           this.username = username;
       }
   
       public String getPassword() {
           return password;
       }
   
       public void setPassword(String password) {
           this.password = password;
       }
   }
   

2. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

   @RestController
   public class HelloController {
   
       //   /error默认错误请求
       @GetMapping("/hello")
       public String hello() {
           return "hello";
       }
   
       //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
       @PostMapping("/user")
       public User user() {
           return new User();
       }
   }
   

3. 重启查看测试

   

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的.

• @ApiModel为类添加注释

• @ApiModelProperty为类属性添加注释

【注意点】：在正式发布的时候，关闭Swagger！！！

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

我们也可以给请求的接口配置一些注释

1. 在HelloController控制类中的接口添加api接口注释

   @RestController
   public class HelloController {
       ......
       @ApiOperation("Hello控制接口")
       @GetMapping("/hello")
       public String hello2(@ApiParam("用户名") String username) {
           return "hello" + username;
       }
       
       @ApiOperation("get测试")
       @GetMapping("/get")
       public User hello2(@ApiParam("用户") User user) {
           return user;
       }
   }
   

   

2. 进行try it out测试

   

   测试结果

   

拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

1、默认的 访问 http://localhost:8080/swagger-ui.html

<dependency> 
   <groupId>io.springfoxgroupId>
   <artifactId>springfox-swagger-uiartifactId>
   <version>2.9.2version>
dependency>

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<dependency>
   <groupId>com.github.xiaoymingroupId>
   <artifactId>swagger-bootstrap-uiartifactId>
   <version>1.9.1version>
dependency>