SpringBoot(45) —— 配置Swagger信息

配置Swagger信息

• 配置swagger需要使用swagger的配置类Docket，并将这个类注入到spring容器中，所以去config中装配Docket实例

• 但是Docket类在配置类中new的时候，需要参数，需要什么参数？看源码

      public Docket(DocumentationType documentationType) {
          this.apiInfo = ApiInfo.DEFAULT;
          this.groupName = "default";
          this.enabled = true;
          this.genericsNamingStrategy = new DefaultGenericTypeNamingStrategy();
          this.applyDefaultResponseMessages = true;
          this.host = "";
          this.pathMapping = Optional.absent();
          this.apiSelector = ApiSelector.DEFAULT;
          this.enableUrlTemplating = false;
          this.vendorExtensions = Lists.newArrayList();
          this.documentationType = documentationType;
      }
  

• 显然，我们需要传入一个DocumentationType 的对象作为参数才能new Docket()，但是我们可以发现这个类只是在构造的最后一行使用的传入的DocumentationType 对象，前面的一系列操作都是在为类Docket赋初始值

• 第一行操作this.apiInfo = ApiInfo.DEFAULT;使用了一个常量ApiInfo.DEFAULT，我们可以去看看这个常量的值

  public static final ApiInfo DEFAULT;
  static {
      DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", 
      DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", 
      new ArrayList());
  }
  

• 看到常量值是不是有点眼熟？
  
  可见，页面上的swagger信息部分显示的数据就是这里配置的

• 再来看第二个参数this.groupName = “default”，是不是也在页面上见过？
  

• 看到这里我们就可以确定，类Docket就是用来配置Swagger的

• 回到Docket构造需要的参数DocumentationType类，我们也可以看一下这个类的源码

  public class DocumentationType extends SimplePluginMetadata {
    public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType SPRING_WEB = new DocumentationType("spring-web", "1.0");
  }
  

• 我们可以发现这个类内部本来就new了3个对象，并且是静态的，所以我们在new DocumentationType()的时候可以使用这3个静态常量，仔细看一看它们之间的区别就是new的时候传入的参数值不一样，我们现在使用的依赖为swagger 2.0，所以我们使用常量2即可

  @Configuration
  @EnableSwagger2 //开启Swagger2
  public class SwaggerConfig {
      @Bean
      public Docket docket(){
          return new Docket(DocumentationType.SWAGGER_2);
      }
  }
  

• 但是就这么就把配置对象存入spring容器中和使用swagger默认值又有什么区别，所以我们一般会在这里配置一些配置参数，怎么配置呢？刚刚在上面不是说到了一个类ApiInfo吗？它内部配置的信息不就是显示在swagger页面上的数据吗？所以我们可以通过修改这个类的参数实现配置swagger页面显示的数据

• 怎么通过Docket类修改ApiInfo类中数据的信息呢？Docket类内部有一个方法

  public Docket apiInfo(ApiInfo apiInfo) {
  	 this.apiInfo = defaultIfAbsent(apiInfo, apiInfo);
  	 return this;
  }
  

• 可见这个方法内部调用了另一个方法defaultIfAbsent()，我们可以看一看这个方法的源码

  public static <T> T defaultIfAbsent(T newValue, T defaultValue) {
      return Optional.fromNullable(newValue).or(Optional.fromNullable(defaultValue)).orNull();
  }
  

• 这个方法显然就是在判断我们有没有为ApiInfo设置新的配置，如果没有，那么ApiInfo将采用原来的默认配置，所以我们就可以使用Docket.apiInfo()修改apiInfo类的配置，并且这个方法返回值也是一个Docket对象，所以我们就可以直接在@Bean方法的返回值处直接"."方法进行参数配置了

• 那么我们可以配置哪些参数呢？可以参考ApiInfo的源码

  public class ApiInfo {
      public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
      public static final ApiInfo DEFAULT;
      
      //以下8个成员变量为可以配置的参数
      private final String version;
      private final String title;
      private final String description;
      private final String termsOfServiceUrl;
      private final String license;
      private final String licenseUrl;
      private final Contact contact;
      private final List<VendorExtension> vendorExtensions;
  }
  

• 上面就是我们可以配置的8个属性，我们可以直接调用ApiInfo的构造方法配置我们自己想要设置的属性

  @Configuration
  @EnableSwagger2 //开启Swagger2
  public class SwaggerConfig {
      @Bean
      public Docket docket(){
          return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfo(
                  "thhh的SwaggerAPI文档",    //标题
                  "thhh学习Swagger",         //描述
                  "v1.0",                   //版本
                  "www.termsOfServiceUrl.com",           //服务条款URL
                  new Contact("thhh", "www.thhh.com", "www.thhh@email.com") ,   //作者信息
                  "Apache 2.0",
                  "http://www.apache.org/licenses/LICENSE-2.0",
                  new ArrayList()
          ));
      }
  
  }
  

• 重启项目测试
  

• 所以所谓的配置Swagger信息，就是在配置一些当前这个swagger的描述信息

• 注意：在配置Swagger信息的时候我们只能通过new ApiInfo()的方式，因为ApiInfo类并没有为属性配置对应的set方法，所以我们只能通过构造来实现信息配置，对于一些我们不想修改的配置需要我们自己将源码中的配置粘贴上去，或者直接传""