文档章节

Spring Boot 2.x基础教程:Swagger接口分类与各元素排序问题详解

程序猿DD
 程序猿DD
发布于 10/09 09:36
字数 2092
阅读 829
收藏 15

之前通过Spring Boot 2.x基础教程:使用Swagger2构建强大的API文档一文,我们学习了如何使用Swagger为Spring Boot项目自动生成API文档,有不少用户留言问了关于文档内容的组织以及排序问题。所以,就特别开一篇详细说说Swagger中文档内容如何来组织以及其中各个元素如何控制前后顺序的具体配置方法。

接口的分组

我们在Spring Boot中定义各个接口是以Controller作为第一级维度来进行组织的,Controller与具体接口之间的关系是一对多的关系。我们可以将同属一个模块的接口定义在一个Controller里。默认情况下,Swagger是以Controller为单位,对接口进行分组管理的。这个分组的元素在Swagger中称为Tag,但是这里的Tag与接口的关系并不是一对多的,它支持更丰富的多对多关系。

默认分组

首先,我们通过一个简单的例子,来看一下默认情况,Swagger是如何根据Controller来组织Tag与接口关系的。定义两个Controller,分别负责教师管理与学生管理接口,比如下面这样:

@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    @GetMapping("/xxx")
    public String xxx() {
        return "xxx";
    }

}

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

}

启动应用之后,我们可以看到Swagger中这两个Controller是这样组织的:

图中标出了Swagger默认生成的Tag与Spring Boot中Controller展示的内容与位置。

自定义默认分组的名称

接着,我们可以再试一下,通过@Api注解来自定义Tag,比如这样:

@Api(tags = "教师管理")
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {

    // ...

}

@Api(tags = "学生管理")
@RestController
@RequestMapping(value = "/student")
static class StudentController {

    // ...

}

再次启动应用之后,我们就看到了如下的分组内容,代码中@Api定义的tags内容替代了默认产生的teacher-controllerstudent-controller

合并Controller分组

到这里,我们还都只是使用了TagController一一对应的情况,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用户,可以通过如下方式:

file

第二种: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的排序配置没有可选项。它提供了两个配置项:alphamethod,分别代表了按字母表排序以及按方法定义顺序排序。当我们不配置的时候,改配置默认为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;

}

最终效果如下:

小结

本文详细的介绍了Swagger中对接口内容的组织控制。有些问题并没有通过配置来解决,也可能是对文档或源码内容的了解不够深入。如果读者有更好的实现方案,欢迎提出与交流。

代码示例

本文的完整工程可以查看下面仓库中的chapter2-4目录:

如果您觉得本文不错,欢迎Star支持,您的关注是我坚持的动力!

相关资料

> 欢迎关注我的公众号:程序猿DD,获得独家整理的学习资源和日常干货推送。 > 如果您对我的专题内容感兴趣,也可以关注我的博客:didispace.com

© 著作权归作者所有

程序猿DD
粉丝 674
博文 117
码字总数 163200
作品 4
闵行
私信 提问
Spring Boot 集成 Swagger,生成接口文档就这么简单!

之前的文章介绍了《推荐一款接口 API 设计神器!》,今天栈长给大家介绍下如何与优秀的 Spring Boot 框架进行集成,简直不能太简单。 你所需具备的基础 告诉你,Spring Boot 真是个牛逼货! ...

Java技术栈
03/19
117
0
Spring Boot 2 快速教程:WebFlux Restful CRUD 实践(三)

摘要: 原创出处 https://www.bysocket.com 「公众号:泥瓦匠BYSocket 」欢迎关注和转载,保留摘要,谢谢! 这是泥瓦匠的第102篇原创 03:WebFlux Web CRUD 实践 文章工程: JDK 1.8 Maven 3....

01/16
0
0
程序猿DD/swagger-butler

Swagger Butler Swagger Butler是一个基于Swagger与Zuul构建的API文档汇集工具。通过构建一个简单的Spring Boot应用,增加一些配置就能将现有整合了Swagger的Web应用的API文档都汇总到一起,...

程序猿DD
2018/05/25
0
0
Spring Boot学习笔记

多模块开发 [SpringBoot学习]-IDEA创建Gradle多Module结构的SpringBoot项目 RabbitMQ RabbitMQ 安装 linux安装RabbitMQ详细教程 Ubuntu 16.04 RabbitMq 安装与运行(安装篇) ubantu安装...

OSC_fly
2018/07/26
0
0
精通Spring Boot——第九篇:整合Swagger在线文档

开发中最烦的一件事是什么?当你全心全意思考的时候,前端笑眯眯的过来了:“大哥,你没告诉我该传什么参数!”......然后一堆吧啦吧啦扯淡,好了,前端大佬心满意足的走了,你以为事情也就这...

liu浪诗人
2018/10/14
224
5

没有更多内容

加载失败,请刷新页面

加载更多

elasticsearch 6.x的基本dsl语句

本文使用的谷歌浏览器插件sense,链接如下sense插件(兼容es6.x版本) 查看集群状态 http://106.12.27.130:9200/_cat/health?v 绿色-一切都很好(集群功能齐全) 黄色——所有的数据都是可用...

长恭
6分钟前
0
0
Math对象的一些方法

<!DOCTYPE html><html><head> <meta charset="UTF-8"> <title></title> <script type="text/javascript"> //圆周率 console.log(Math.PI) ......

zhengzhixiang
12分钟前
1
0
移动端的弹窗滚动禁止body滚动

本文转载于:专业的前端网站➼移动端的弹窗滚动禁止body滚动 前言 最近一个需求是弹窗展示列表,显然是需要一个滚动条的,而滚动到底部就会穿透到body滚动,而阻止默认行为是不行的,这样两个...

前端老手
35分钟前
8
0
设计模式 建造者模式和模板方法模式扩展篇

建造者模式和模板方法模式扩展篇 UML 与抽象工厂模式比较 本模式可以看出与抽象工厂非常类似,都是产生不同的产品,怎么区分这两种设计的使用场景呢 - 建造者模式关注的是基本方法的调...

木本本
39分钟前
11
0
CPU 读取cache、内存、磁盘性能

google 工程师Jeff Dean 首先在他关于分布式系统的ppt文档列出来的,到处被引用的很多。 1秒=10^3毫秒=10^6微妙=10^9纳秒=10^12皮秒 读 cache ns 级,读内存100 ns,从内存顺序读1MB 0.25ms,...

SibylY
47分钟前
7
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部