目录
1.数据接口分组配置2.实体类注解信息配置3.数据接口注解信息配置4.在线测试数据接口(swagger强大之处)5.小结
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类中有专门的方法可以配置组名称
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");
boolean flag
= environment
.acceptsProfiles(profile
);
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;
return user
;
}
可见即使是错误也是可以将信息提示出来的上面的在线测试数据接口就是swagger的强大之处
5.小结
我们可以通过swagger的注解给一些难以理解的实体类、实体类的属性、数据接口、接口的参数等等加上注释信息swagger页面上的数据接口/API是实时更新的可以在线测试数据接口/API每个人开发的数据接口可以作为一个组分开管理
以上swagger的特点就可以很好的解决前后端分离造成的沟通不及时问题，国内几乎所有大厂都在使用 唯一的注意点：出于安全考虑，在正式发布的时候关闭swagger，并且可以节约使用内存
我们需要掌握的swagger的知识点
使用swagger的5个常用注释会修改swagger页面上swagger信息会操作swagger页面上的接口信息会操作swagger页面上的分组信息会操作swagger页面上的实体类/model信息会使用swagger在线测试数据接口 小结下来就是要会操作swagger页面+会在线测试数据接口
