Spring Boot集成Swagger接口分类与各元素排序问题
在上一篇中我们完成使用JSR-303校验，以及利用Swagger2得到相关接口文档，这节，我们在原先的基础之上，完成Swagger中关于对各个元素之间控制前后顺序的具体配置方法。
Swagger的接口的分组
首先我们需要对Swagger中的接口也就是以Controller 层作为第一级梯度进行组织的，Controller在我们实际开发中，与其他具体接口之间是存在一对多的关系，我们可以将同属一个模块的接口定义在一个Controller 中，默认情况之下，我们的Swagger 是以Controller为单位，对接口进行分组管理，在Swagger 中，这个分组的元素被称为Tag,但是这里的Tag与接口的关系并不是一对多关系，它支持更加丰富的多对多的关系，
默认的分组
首先通过创建一个简单的例子进，来看一下，我们是如何处理Swagger是如如何根据Controller来组织Tag与接口关系的，定义两个Controller，分别负责教师管理与学生管理接口，为了重复利用代码，我们就在上一篇的基础之上进行代码添加了：
为了简单明了，我均将下列代码放在Application类里边
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
@GetMapping("/miaow")
public String miaow() {
return "miaow";
}
}
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation("获取学生清单")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
@ApiOperation("获取教某个学生的老师清单")
@GetMapping("/his-teachers")
public String ccc() {
return "ccc";
}
@ApiOperation("创建一个学生")
@PostMapping("/aaa")
public String aaa() {
return "aaa";
}
}此时通过：localhost:8080/swagger-ui.html 访问得到我们Swagger的组织结构是
在上图中我们了解到我们定义的控制层，得到的swagger生成的默认结构展示出来了。
application.properties文件
swagger.title=spring-boot-starter-swagger swagger.description=Starter for swagger 2.x swagger.version=1.9.0.RELEASE swagger.license=Apache License, Version 2.0 swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger swagger.contact.name=miaow swagger.contact.url=https://luoxiaohei520.github.io swagger.contact.email=miaow@qq.com swagger.base-package=com.didispace swagger.base-path=/** swagger.ui-config.tags-sorter=alpha swagger.ui-config.operations-sorter=alpha
在启动类添加相关控制层接口：
@EnableSwagger2Doc
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
@Api(tags = {"1-教师管理","3-教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
@ApiOperation(value = "miaow")
@GetMapping("/miaow")
public String miaow() {
return "miaow";
}
}
@Api(tags = {"2-学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation(value = "获取学生清单", tags = "3-教学管理")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
@ApiOperation("获取教某个学生的老师清单")
@GetMapping("/his-teachers")
public String ccc() {
return "ccc";
}
@ApiOperation("创建一个学生")
@PostMapping("/aaa")
public String aaa() {
return "aaa";
}
}
}得到结果集
自定义默认分组的名称
@Api(tags = "教师管理")
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
// ...
}
@Api(tags = "学生管理")
@RestController
@RequestMapping(value = "/student")
static class StudentController {
// ...
}我们在Api的tags修改成为我们想要的表达文字：
合并Controller分组
在此，我们使用了Tag和Controller 一一对应的情况，Swagger中还支持更加灵活的分组！从@Api注解中，我们如果有去看详细代码的时候，发现tags属性其实是一个数组类型。
因而，我们可以通过地定义同名的Tag来汇总Controller中的相关接口，比如我们可以定义一个Tag为“教学管理“，让这个分组同时包含教师管理和学生管理的所有接口，案例如下：
@Api(tags = {"教师管理", "教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
// ...
}
@Api(tags = {"学生管理", "教学管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
// ...
}更新细粒度的接口分组
通过@Api可以实现将Controller中的接口合并到一个Tag中,但是如果我们希望精确到某个接口的合并，我们应该如何做?
@Api(tags = {"教师管理","教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
@ApiOperation(value = "maiow")
@GetMapping("/miaow")
public String miaow() {
return "miaow";
}
}
@Api(tags = {"学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation(value = "获取学生清单", tags = "教学管理")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
@ApiOperation("获取教某个学生的老师清单")
@GetMapping("/his-teachers")
public String ccc() {
return "ccc";
}
@ApiOperation("创建一个学生")
@PostMapping("/aaa")
public String aaa() {
return "aaa";
}
}得到效果图：
内容的顺序
在完成了接口的分组后，我们可以进行对接口内容的展示顺序进行调整，其中，我们主要涉及三个方面：分组的排序、接口的排序、以及参数的排序。
分组排序
关于分组排序，也就是Tag的排序。目前版本的Swagger支持并不太好，通过文档我们可以找到关于Tag排序的配置方法。
第一种，适合原生的Swagger用户，修改：
第二种方式：Swagger Starter用户，可以通过修改配置的方式：
swagger.ui-config.tags-sorter=alpha
修改上述的配置的源码：
public enum TagsSorter {
ALPHA("alpha");
private final String value;
TagsSorter(String value) {
this.value = value;
}
@JsonValue
public String getValue() {
return value;
}
public static TagsSorter of(String name) {
for (TagsSorter tagsSorter : TagsSorter.values()) {
if (tagsSorter.value.equals(name)) {
return tagsSorter;
}
}
return null;
}
}我们可以发现Swagger 提供考虑一个选项，就是按照字字母顺序进行排序。
@Api(tags = {"1-教师管理","3-教学管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
// ...
}
@Api(tags = {"2-学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation(value = "获取学生清单", tags = "3-教学管理")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
// ...
}
接口的排序
在完成了分组排序问题（虽然不太优雅…）之后，在来看看同一分组内各个接口该如何实现排序。同样的，凡事先查文档，可以看到Swagger也提供了相应的配置，下面也分两种配置方式介绍：
第一种还是适合原生Swagger用户的，可以修改：
第二种：Swagger Starter用户，可以通过修改配置方式：
swagger.ui-config.operations-sorter=alpha
这个配置不像Tag的排序配置没有可选项。它提供了两个配置项：alpha和method，分别代表了按字母表排序以及按方法定义顺序排序。当我们不配置的时候，改配置默认为alpha。
参数的排序
完成了接口的排序后，更加细粒度的就是请求参数的排序了，在默认的情况下，我们的Swagger会对Model的参数内容展示进行按照字母排序，我们的展示的User在Swagger之前是这样的：
现在，我们希望可以按照Model中定义的成员变量顺序来展示，那么需要我们通过@ApiModelProperty 注解的position参数来实现位置的设置。
对应的User对象如下：
w未加
@ApiModel(description = "用户实体")
public class User {
@ApiModelProperty(value = "用户编号", position = 1)
private Long id;
@NotNull
@Size(min = 2, max = 5)
@ApiModelProperty(value = "用户姓名", position = 2)
private String name;
@NotNull
@Max(100)
@Min(10)
@ApiModelProperty(value = "用户年龄", position = 3)
private Integer age;
@NotNull
@Email
@ApiModelProperty(value = "用户邮箱", position = 4)
private String email;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
public User(Long id, String name, Integer age, String email) {
this.id = id;
this.name = name;
this.age = age;
this.email = email;
}
public User() {
}
}加了Position之后的swagger展示：
到此这篇关于Spring Boot集成Swagger接口分类与各元素排序问题的文章就介绍到这了,更多相关Spring Boot集成Swagger接口内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
详解Spring Boot中使用AOP统一处理Web请求日志
本篇文章主要介绍了详解Spring Boot中使用AOP统一处理Web请求日志，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2017-05-05
这篇文章主要介绍了Java获得一个数组的指定长度排列组合算法,结合实例形式分析了java排列组合相关数组遍历、运算操作技巧,需要的朋友可以参考下2019-06-06
这篇文章主要介绍了IDEA 2021.1 的 Win 和 Mac 快捷键大全,本文是小编给大家精心收藏的，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下2021-04-04
在本文里我们给大家分享了关于java多线程中线程封闭的知识点内容以及用法，有需要读者们可以参考下。2019-07-07
这篇文章主要介绍了Springboot @Value使用代码实例,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下2019-11-11
日常开发中, 我们会经常遇到时间的运算, 操作, 格式化等, 这篇文章主要为大家详细介绍了LocalTime的常用时间操作,感兴趣的小伙伴可以了解一下2023-11-11
这篇文章主要介绍了Java Socket实现单线程通信的方法,结合具体实例形式分析了java socket单线程通信的原理与客户端、服务器端相关实现技巧,需要的朋友可以参考下2017-06-06
这篇文章主要介绍了Java遍历文件夹及子目录代码实例,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下2020-07-07
这篇文章主要介绍了解决mapper接口无法映射mapper.xml的问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2023-06-06
springboot如何解决跨域后session获取不到sessionId不一致
这篇文章主要介绍了springboot如何解决跨域后session获取不到sessionId不一致问题,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教2024-01-01
最新评论