Shulou(Shulou.com)06/02 Report--

What are the categories of Swagger interfaces in Spring Boot 2.x? For this problem, this article introduces the corresponding analysis and solutions in detail, hoping to help more partners who want to solve this problem find simpler and easier ways.

default packet

First, let's take a look at a simple example of how Swagger organizes Tag and interface relationships according to Controller by default. Define two Controllers, responsible for teacher management and student management interfaces respectively, such as the following:

@RestController@RequestMapping(value = "/teacher")static class TeacherController { @GetMapping("/xxx") public String xxx() { return "xxx"; }}@RestController@RequestMapping(value = "/student")static class StudentController { @ApiOperation("Get Student List") @GetMapping("/list") public String bbb() { return "bbb"; } @ApiOperation("Get a list of teachers who teach a student") @GetMapping("/his-teachers") public String ccc() { return "ccc"; } @ApiOperation("Create a Student") @PostMapping("/aaa") public String aaa() { return "aaa"; }}

After launching the app, we can see that the two Controllers in Swagger are organized like this:

The figure marks the Tag generated by Swagger by default and the content and location of the Controller display in Spring Boot.

Customize the name of the default grouping

Next, we can try again and customize Tag with @Api annotation, such as this:

@Api(tags = "Teacher Management")@RestController@RequestMapping(value = "/teacher")static class TeacherController { // ...}@ Api(tags = "Student Management")@RestController@RequestMapping(value = "/student")static class StudentController { // ...}

After launching the application again, we see the following grouping content. The tags defined by @Api in the code replace the teacher-controller and student-controller generated by default.

合并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中，但是如果我们希望精确到某个接口的合并呢？比如这样的需求："教学管理"包含"教师管理"中所有接口以及"学生管理"管理中的"获取学生清单"接口（不是全部接口）。

那么上面的实现方式就无法满足了。这时候发，我们可以通过使用@ApiOperation注解中的tags属性做更细粒度的接口分类定义，比如上面的需求就可以这样子写：

@Api(tags = {"教师管理","教学管理"})@RestController@RequestMapping(value = "/teacher")static class TeacherController { @ApiOperation(value = "xxx") @GetMapping("/xxx") public String xxx() { return "xxx"; }}@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只提供了一个选项，就是按字母顺序排列。那么我们要如何实现排序呢？这里笔者给一个不需要扩展源码，仅依靠使用方式的定义来实现排序的建议：为Tag的命名做编号。比如：

@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对象在文章中展现如下：

如果我们希望可以按照Model中定义的成员变量顺序来展现，那么需要我们通过@ApiModelProperty注解的position参数来实现位置的设置，比如：

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

最终效果如下：

关于Spring Boot 2.x中Swagger接口有哪些分类问题的解答就分享到这里了，希望以上内容可以对大家有一定的帮助，如果你还有很多疑惑没有解开，可以关注行业资讯频道了解更多相关知识。

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.