Spring Boot集成Swagger接口分類與各元素排序問(wèn)題
在上一篇中我們完成使用JSR-303校驗(yàn)，以及利用Swagger2得到相關(guān)接口文檔，這節(jié)，我們?cè)谠鹊幕A(chǔ)之上，完成Swagger中關(guān)于對(duì)各個(gè)元素之間控制前后順序的具體配置方法。
Swagger的接口的分組
首先我們需要對(duì)Swagger中的接口也就是以Controller 層作為第一級(jí)梯度進(jìn)行組織的，Controller在我們實(shí)際開(kāi)發(fā)中，與其他具體接口之間是存在一對(duì)多的關(guān)系，我們可以將同屬一個(gè)模塊的接口定義在一個(gè)Controller 中，默認(rèn)情況之下，我們的Swagger 是以Controller為單位，對(duì)接口進(jìn)行分組管理，在Swagger 中，這個(gè)分組的元素被稱為Tag,但是這里的Tag與接口的關(guān)系并不是一對(duì)多關(guān)系，它支持更加豐富的多對(duì)多的關(guān)系，
默認(rèn)的分組
首先通過(guò)創(chuàng)建一個(gè)簡(jiǎn)單的例子進(jìn)，來(lái)看一下，我們是如何處理Swagger是如如何根據(jù)Controller來(lái)組織Tag與接口關(guān)系的，定義兩個(gè)Controller，分別負(fù)責(zé)教師管理與學(xué)生管理接口，為了重復(fù)利用代碼，我們就在上一篇的基礎(chǔ)之上進(jìn)行代碼添加了：
為了簡(jiǎn)單明了，我均將下列代碼放在Application類里邊
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
@GetMapping("/miaow")
public String miaow() {
return "miaow";
}
}
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation("獲取學(xué)生清單")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
@ApiOperation("獲取教某個(gè)學(xué)生的老師清單")
@GetMapping("/his-teachers")
public String ccc() {
return "ccc";
}
@ApiOperation("創(chuàng)建一個(gè)學(xué)生")
@PostMapping("/aaa")
public String aaa() {
return "aaa";
}
}此時(shí)通過(guò)：localhost:8080/swagger-ui.html 訪問(wèn)得到我們Swagger的組織結(jié)構(gòu)是
在上圖中我們了解到我們定義的控制層，得到的swagger生成的默認(rèn)結(jié)構(gòu)展示出來(lái)了。
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
在啟動(dòng)類添加相關(guān)控制層接口：
@EnableSwagger2Doc
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
@Api(tags = {"1-教師管理","3-教學(xué)管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
@ApiOperation(value = "miaow")
@GetMapping("/miaow")
public String miaow() {
return "miaow";
}
}
@Api(tags = {"2-學(xué)生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation(value = "獲取學(xué)生清單", tags = "3-教學(xué)管理")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
@ApiOperation("獲取教某個(gè)學(xué)生的老師清單")
@GetMapping("/his-teachers")
public String ccc() {
return "ccc";
}
@ApiOperation("創(chuàng)建一個(gè)學(xué)生")
@PostMapping("/aaa")
public String aaa() {
return "aaa";
}
}
}得到結(jié)果集
自定義默認(rèn)分組的名稱
@Api(tags = "教師管理")
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
// ...
}
@Api(tags = "學(xué)生管理")
@RestController
@RequestMapping(value = "/student")
static class StudentController {
// ...
}我們?cè)贏pi的tags修改成為我們想要的表達(dá)文字：
合并Controller分組
在此，我們使用了Tag和Controller 一一對(duì)應(yīng)的情況，Swagger中還支持更加靈活的分組！從@Api注解中，我們?nèi)绻腥タ丛敿?xì)代碼的時(shí)候，發(fā)現(xiàn)tags屬性其實(shí)是一個(gè)數(shù)組類型。
因而，我們可以通過(guò)地定義同名的Tag來(lái)匯總Controller中的相關(guān)接口，比如我們可以定義一個(gè)Tag為“教學(xué)管理“，讓這個(gè)分組同時(shí)包含教師管理和學(xué)生管理的所有接口，案例如下：
@Api(tags = {"教師管理", "教學(xué)管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
// ...
}
@Api(tags = {"學(xué)生管理", "教學(xué)管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
// ...
}更新細(xì)粒度的接口分組
通過(guò)@Api可以實(shí)現(xiàn)將Controller中的接口合并到一個(gè)Tag中,但是如果我們希望精確到某個(gè)接口的合并，我們應(yīng)該如何做?
@Api(tags = {"教師管理","教學(xué)管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
@ApiOperation(value = "maiow")
@GetMapping("/miaow")
public String miaow() {
return "miaow";
}
}
@Api(tags = {"學(xué)生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation(value = "獲取學(xué)生清單", tags = "教學(xué)管理")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
@ApiOperation("獲取教某個(gè)學(xué)生的老師清單")
@GetMapping("/his-teachers")
public String ccc() {
return "ccc";
}
@ApiOperation("創(chuàng)建一個(gè)學(xué)生")
@PostMapping("/aaa")
public String aaa() {
return "aaa";
}
}得到效果圖：
內(nèi)容的順序
在完成了接口的分組后，我們可以進(jìn)行對(duì)接口內(nèi)容的展示順序進(jìn)行調(diào)整，其中，我們主要涉及三個(gè)方面：分組的排序、接口的排序、以及參數(shù)的排序。
分組排序
關(guān)于分組排序，也就是Tag的排序。目前版本的Swagger支持并不太好，通過(guò)文檔我們可以找到關(guān)于Tag排序的配置方法。
第一種，適合原生的Swagger用戶，修改：
第二種方式：Swagger Starter用戶，可以通過(guò)修改配置的方式：
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;
}
}我們可以發(fā)現(xiàn)Swagger 提供考慮一個(gè)選項(xiàng)，就是按照字字母順序進(jìn)行排序。
@Api(tags = {"1-教師管理","3-教學(xué)管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
// ...
}
@Api(tags = {"2-學(xué)生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
@ApiOperation(value = "獲取學(xué)生清單", tags = "3-教學(xué)管理")
@GetMapping("/list")
public String bbb() {
return "bbb";
}
// ...
}
接口的排序
在完成了分組排序問(wèn)題（雖然不太優(yōu)雅…）之后，在來(lái)看看同一分組內(nèi)各個(gè)接口該如何實(shí)現(xiàn)排序。同樣的，凡事先查文檔，可以看到Swagger也提供了相應(yīng)的配置，下面也分兩種配置方式介紹：
第一種還是適合原生Swagger用戶的，可以修改：
第二種：Swagger Starter用戶，可以通過(guò)修改配置方式：
swagger.ui-config.operations-sorter=alpha
這個(gè)配置不像Tag的排序配置沒(méi)有可選項(xiàng)。它提供了兩個(gè)配置項(xiàng)：alpha和method，分別代表了按字母表排序以及按方法定義順序排序。當(dāng)我們不配置的時(shí)候，改配置默認(rèn)為alpha。
參數(shù)的排序
完成了接口的排序后，更加細(xì)粒度的就是請(qǐng)求參數(shù)的排序了，在默認(rèn)的情況下，我們的Swagger會(huì)對(duì)Model的參數(shù)內(nèi)容展示進(jìn)行按照字母排序，我們的展示的User在Swagger之前是這樣的：
現(xiàn)在，我們希望可以按照Model中定義的成員變量順序來(lái)展示，那么需要我們通過(guò)@ApiModelProperty 注解的position參數(shù)來(lái)實(shí)現(xiàn)位置的設(shè)置。
對(duì)應(yīng)的User對(duì)象如下：
w未加
@ApiModel(description = "用戶實(shí)體")
public class User {
@ApiModelProperty(value = "用戶編號(hào)", 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展示：
到此這篇關(guān)于Spring Boot集成Swagger接口分類與各元素排序問(wèn)題的文章就介紹到這了,更多相關(guān)Spring Boot集成Swagger接口內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
這篇文章主要介紹了iReport使用指南及常見(jiàn)功能，本文以iReport 3.5.1為例，通過(guò)示例演示給大家介紹的非常詳細(xì)，需要的朋友可以參考下2021-10-10
Java實(shí)現(xiàn)消消樂(lè)中的消除功能
這篇文章主要為大家詳細(xì)介紹了Java實(shí)現(xiàn)消消樂(lè)中的消除功能，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2021-07-07
Spring?Boot?JWT登錄授權(quán)使用(無(wú)感刷新)
JWT作為一種輕量級(jí)的身份認(rèn)證與授權(quán)方案,憑借其無(wú)狀態(tài)、可跨域、易于擴(kuò)展的特性,成為?Spring?Boot?項(xiàng)目中實(shí)現(xiàn)認(rèn)證授權(quán)的主流選擇,本文詳解Spring?Boot整合?JWT?實(shí)現(xiàn)登錄認(rèn)證與授權(quán)的全流程,助力開(kāi)發(fā)者快速搭建安全可靠的認(rèn)證授權(quán)體系,感興趣的可以了解一下2026-04-04
Java實(shí)現(xiàn)電影院訂票系統(tǒng)代碼
這篇文章主要介紹了Java實(shí)現(xiàn)電影院訂票系統(tǒng)代碼，代碼實(shí)現(xiàn)了界面類登錄注冊(cè)類，用戶類等，具有一定參考價(jià)值，需要的朋友可以參考下。2017-11-11
詳解如何通過(guò)Java實(shí)現(xiàn)類似Nginx代理
最近遇到一個(gè)問(wèn)題,在內(nèi)網(wǎng)環(huán)境中部署的項(xiàng)目需要調(diào)用外網(wǎng)完成一些應(yīng)用,一般情況我們可以通過(guò)增加一臺(tái)機(jī)器,部署到可以訪問(wèn)外網(wǎng)的服務(wù)器上,然后內(nèi)網(wǎng)直接連接該機(jī)器通過(guò)Nginx進(jìn)行代理即可,所以本文介紹了如何通過(guò)Java實(shí)現(xiàn)類似Nginx代理,需要的朋友可以參考下2024-08-08
java實(shí)現(xiàn)RTF文件查看器(附帶源碼)
這篇文章主要介紹了一個(gè)基于?Java?Swing?的?RTF?文件查看器,既可作為輕量級(jí)桌面應(yīng)用,也可嵌入到更大規(guī)模的管理系統(tǒng)中,滿足用戶對(duì)?RTF?文檔的即時(shí)預(yù)覽、樣式保真和簡(jiǎn)單導(dǎo)航需求2025-06-06
java發(fā)送post請(qǐng)求使用multipart/form-data格式文件數(shù)據(jù)到接口代碼示例
這篇文章主要介紹了java發(fā)送post請(qǐng)求使用multipart/form-data格式文件數(shù)據(jù)到接口的相關(guān)資料,文中指定了數(shù)據(jù)編碼格式為UTF-8,并強(qiáng)調(diào)了所需依賴工具類,需要的朋友可以參考下2024-12-12
注意Java中?new?BigDecimal(double?val)?的使用
這篇文章主要介紹了注意Java中?new?BigDecimal(double?val)?的使用，文章圍繞主題展開(kāi)詳細(xì)的內(nèi)容介紹，具有一定的參考價(jià)值，需要的朋友可以參考一下2022-07-07
這篇文章主要介紹了Java 抽象類與接口的對(duì)比，幫助大家更好的理解和學(xué)習(xí)Java，感興趣的朋友可以了解下2020-08-08
這篇文章主要介紹了JAVA socket.io注解原理及用法圖解,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-06-06