---

1.数据接口分组配置

• 配置API文档的分组
  
• 我们可以看到swagger页面上有一个下拉列表，组信息；就是我们需要对不同的数据接口API进行分组，通过组信息/选择某一个组别，我们可以方便查看不同 类别/组中 的数据API
• 一看这就是在配置swagger页面上的东西，所以我们还是需要使用到swagger的配置类Docket，我们可以再次回顾一下Docket类中可以配置的参数

  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;
  }
  

• 第1参数我们见过了，就是通过ApiInfo类配置页面上的swagger信息，就是对于这个swagger中数据接口的一个概述+作者信息
• 第3个参数我们也使用过了，通过设置参数enabled的值，我们可以自定义开启还是关闭swagger功能
• 我们可以看看第二个参数groupName ，见名知意，组名称，那么和组信息相关的配置应该就是通过这个属性来配置了
• 和enabled属性同理，Docket类中有专门的方法可以配置组名称

   /**
    * If more than one instance of Docket exists, each one must have a unique groupName as
    * supplied by this method. Defaults to "default".
    *
    * @param groupName - the unique identifier of this swagger group/configuration
    * @return this Docket
    */
   public Docket groupName(String groupName) {
     this.groupName = defaultIfAbsent(groupName, this.groupName);
     return this;
   }
  

• 调用Docket.groupName()

  @Bean
  public Docket docket(Environment environment){
      Profiles profile = Profiles.of("dev","test");//如果当前的配置文件是dev/test，就返回一个实例
      boolean flag = environment.acceptsProfiles(profile);//如果这个Profiles实例/参数代表的配置文件被激活了，就返回true，否则返回false
  
      return new Docket(DocumentationType.SWAGGER_2)
              .enable(flag)
              .groupName("thhh")
              .apiInfo(this.apiInfo())
              .select().apis(RequestHandlerSelectors.basePackage("com.thhh.swagger.controller"))
              .build();
  }
  

• 测试
  
  
• 从上面的测试结果我们可以发现，只有一个组别信息，这显然不是组信息设置的初衷，它的设计初衷应该是有多个组别可以选择，我们可以通过选择不同的组别查看不同类别的组中对应的数据接口，而不用将整个项目的数据接口放在一个页面上进行展示，这样要精确定位一个数据接口很麻烦
• 那么此时我们需要做的就是多搞几个组出来，好让swagger页面上的组信息可选>1
• 思考：为什么会有这个组别信息？因为我们在注入的spring容器的Docket类中配置了我们的组信息
• 猜测：一个注入spring容器中的Docket对象代表了一个组别信息，那么我们想要在swagger页面上选择切换多个组别的数据接口进行查看，我们需要向spring容器中注入多个Docket对象
• 实验：在config中多写几个注册Docket类的@Bean方法

  @Bean
  public Docket docket1(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("B");
  }
  @Bean
  public Docket docket2(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("C");
  }
  @Bean
  public Docket docket3(){
      return new Docket(DocumentationType.SWAGGER_2).groupName("D");
  }
  

• 测试
  
• 注意：上面新增的3个@Bean方法由于除了组信息之外的其他什么信息都没有配置，所以它们显示的数据就是swagger默认配置的，扫描所有的数据接口进行展示，所以必然3个页面会有两个controller的数据接口信息；并且swagger信息也是默认的
• 仔细看一看上图，果然如此
• 分组的好处：一个人开发的模块就是一个组，我们的组名称就可以取当前开发这个模块的人的名称/这个模块的功能名称，这样别人在查看swagger中接口信息的时候就可以很清楚的找打你开发的数据API的信息了；这样就有了协同开发的基础了

---

• 但是我们可以对比一下我们自定义的thhh页面和swagger默认页面，我们可以发现swagger默认页面有一个交model的模块
  
• model模块就是存储的当前你的这个模块中的实体类的信息

2.实体类注解信息配置

• 创建pojo user

  package com.thhh.swagger.pojo;
  
  import lombok.AllArgsConstructor;
  import lombok.Data;
  import lombok.NoArgsConstructor;
  
  @Data
  @NoArgsConstructor
  @AllArgsConstructor
  public class User {
      private Integer id;
      private String username;
      private String password;
  }
  

• 我们创建的实体类怎么才能被swagger扫描到呢？
• 首选我们回忆一下swagger是做什么的？数据接口，它会扫描的只有数据接口，所以我们想要实体类被swagger扫描到，我们只有将实体类和接口关联起来；做法：只要我们的controller中的方法返回了实体类对象，那么这个实体类就会被swagger扫描到
• 所以我们可以去controller中定义一个返回User对象的方法

  @GetMapping("/user")
  public User user(){
      return new User();
  }
  

• 测试
  
• 从上面的结果可以看出，默认的swagger配置还会扫描出一些框架的实体类，这些显然不是我们i想看的，所以我们一般都会自己配置Docket对象，我们可以查看一下我们自己配置的thhh组的model信息
  
• 但是如果我们将使用的lombok去掉，看看会发生什么
  
• 所以想要swagger获取实体类的属性信息，①写上属性的get() ②属性public

---

• 在实体类上我们还常用5个注解，注解主要用于对我们的实体类和实体类的属性进行注释，这个注释就是解释的意思，因为实际开发中有些类和类的属性非常复杂，所以我们需要使用swagger的注解为类和类的数据加上注释，帮助使用数据API的人理解实体类和实体类的属性
  • @ApiModel(“实体类的描述信息”)，就是为了帮助别人理解这个实体类的作用的，即文档注释
  • @ApiModelProperty(“属性的描述信息”)，就是为了帮助别人理解这个属性的作用的

  package com.thhh.swagger.pojo;
  
  import io.swagger.annotations.ApiModel;
  import io.swagger.annotations.ApiModelProperty;
  import lombok.AllArgsConstructor;
  import lombok.Data;
  import lombok.NoArgsConstructor;
  
  @Data
  @NoArgsConstructor
  @AllArgsConstructor
  @ApiModel("User-用户实体类")
  public class User {
      @ApiModelProperty("用户ID")
      private Integer id;
      @ApiModelProperty("用户名")
      private String username;
      @ApiModelProperty("用户密码")
      private String password;
  }
  

• 测试
  

3.数据接口注解信息配置

• @Api(tags = “接口信息名称”,description = “接口信息描述”)

  @Api(tags = "接口信息名称,默认就是Controller类的名称",description = "接口信息描述,默认也是Controller类的名称，并且这个属性过期声明了")
  @RestController
  public class HelloController {}
  

• @ApiOperation，用于说明controller中的方法的作用，或者说在swagger中说明某一个数据接口的作用

  @ApiOperation("用于让swagger扫描到User实体类")
  @GetMapping("/user")
  public User user(){
      return new User();
  }
  

• @ApiParam，用于说明数据接口的方法中参数列表中的参数的作用

      @ApiOperation("用于让swagger扫描到User实体类")
      @GetMapping("/user")
      public User user(@ApiParam("用于说明数据接口对应的方法的参数的作用") String name){
          return new User();
      }
  

• 可以发现，我们常用的5个注解都是在配置一些描述信息，用于别人调用我们的数据API的时候可以明确我们的数据接口(@ApiOperation)、数据接口集(@Api)、接口中的参数(@ApiParam)、实体类的作用(@ApiModel)、实体类中成员属性(@ApiModelProperty)的作用
• 其实对于我们本身实现功能没有什么意义，主要还是方便别人调用我们的数据接口

---

4.在线测试数据接口(swagger强大之处)

• 将刚刚使用的user()方法进行改造，让他传递的参数为一个User对象，并最后将则个User对象返回

  @ApiOperation("用于让swagger扫描到User实体类")
  @PostMapping("/user")
  public User user(@ApiParam("用于说明数据接口对应的方法的参数的作用") User user){
      return user;
  }
  

• 假设我们故意在数据接口中制造错误

  @ApiOperation("用于让swagger扫描到User实体类")
  @PostMapping("/user")
  public User user(@ApiParam("用于说明数据接口对应的方法的参数的作用") User user){
      int i = 5/0;	//除0错误
      return user;
  }
  

• 可见即使是错误也是可以将信息提示出来的
• 上面的在线测试数据接口就是swagger的强大之处

---

5.小结

• 我们可以通过swagger的注解给一些难以理解的实体类、实体类的属性、数据接口、接口的参数等等加上注释信息
• swagger页面上的数据接口/API是实时更新的
• 可以在线测试数据接口/API
• 每个人开发的数据接口可以作为一个组分开管理

    以上swagger的特点就可以很好的解决前后端分离造成的沟通不及时问题，国内几乎所有大厂都在使用
    唯一的注意点：出于安全考虑，在正式发布的时候关闭swagger，并且可以节约使用内存

• 我们需要掌握的swagger的知识点
  • 使用swagger的5个常用注释
  • 会修改swagger页面上swagger信息
  • 会操作swagger页面上的接口信息
  • 会操作swagger页面上的分组信息
  • 会操作swagger页面上的实体类/model信息
  • 会使用swagger在线测试数据接口
• 小结下来就是要会操作swagger页面+会在线测试数据接口