Swagger2配置

一 swagger简介

二 配置Swagger

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

1.创建一个springBoot web项目

2.添加依赖库

 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

3.创建Swagger配置类

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

见下图

4.创建Controller控制类

@RestController
public class HelloController {

    @RequestMapping(value = "/hello")
    public String hello(){
      return "hello";
    }
}

5.配置Swagger 配置类

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

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

(2)通过配置ApiInfo属性配置文档信息

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

    public ApiInfo apiInfo(){

        Contact DEFAULT_CONTACT = new Contact("殷会东", "https://blog.csdn.net/qq_41199502?spm=1001.2101.3001.5343", "1874315714@qq.com");
        return  new ApiInfo("殷会东",
                "Api Documentation",
                "1.0",
                "https://blog.csdn.net/qq_41199502?spm=1001.2101.3001.5343",
                 DEFAULT_CONTACT ,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

(3) Docket 实例关联上 apiInfo()

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

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

6. 配置扫描接口

(1) 通过select方法配置怎样扫描接口

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.example.swagger_demo.controller"))
                   .build();
    }

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

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

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

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

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

7.配置Swagger开关

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

在实际开发中，当项目上线时，为了安全我们会关闭Swagger，我们一般不去改源代码，而去更改配置文件。因此我们可以创建一个开发时的运行环境，一个上线是的运行环境。那怎么让项目识别运行的哪个环境的项目呢？

我们可以在Swaggerpe配置类中导入Environment类，通过Environment类来判断我们运行的哪一个环境。
1.创建一个开发是的环境和上线时的环境

2.激活运行环境

3.设置运行环境端口


（4）判断是否为运行swagger应该显示的运行环境

 @Bean
    public Docket docket(Environment environment){

        //设置要显示的运行环境
        Profiles of = Profiles.of("dev","test");
        // 判断当前是否处于该环境
        boolean flag=environment.acceptsProfiles(of);

        return new Docket(DocumentationType.SWAGGER_2)
                   .apiInfo(apiInfo())
                   .enable(flag)//判断是否要显示swagger运行环境
                   .select()
                   .apis(RequestHandlerSelectors.basePackage("com.example.swagger_demo.controller"))
                   .build();
    }

（2）查看效果

注意：dev环境的运行端口号为8081

8.配置APi分组

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

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

（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) 重启项目查看即可