Spring Boot集成Swagger接口分類與各元素排序問題

更新時間：2023年10月27日 10:08:37 作者：Miaow.Y.Hu

這篇文章主要介紹了Spring Boot集成Swagger接口分類與各元素排序問題,首先我們需要對Swagger中的接口也就是以Controller 層作為第一級梯度進(jìn)行組織的,Controller在我們實際開發(fā)中,與其他具體接口之間是存在一對多的關(guān)系,本文給大家介紹的非常詳細(xì),需要的朋友參考下吧

Swagger的接口的分組

首先我們需要對Swagger中的接口也就是以Controller 層作為第一級梯度進(jìn)行組織的，Controller在我們實際開發(fā)中，與其他具體接口之間是存在一對多的關(guān)系，我們可以將同屬一個模塊的接口定義在一個Controller 中，默認(rèn)情況之下，我們的Swagger 是以Controller為單位，對接口進(jìn)行分組管理，在Swagger 中，這個分組的元素被稱為Tag,但是這里的Tag與接口的關(guān)系并不是一對多關(guān)系，它支持更加豐富的多對多的關(guān)系，

默認(rèn)的分組

首先通過創(chuàng)建一個簡單的例子進(jìn)，來看一下，我們是如何處理Swagger是如如何根據(jù)Controller來組織Tag與接口關(guān)系的，定義兩個Controller，分別負(fù)責(zé)教師管理與學(xué)生管理接口，為了重復(fù)利用代碼，我們就在上一篇的基礎(chǔ)之上進(jì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("獲取教某個學(xué)生的老師清單")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }
    @ApiOperation("創(chuàng)建一個學(xué)生")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }
}

此時通過：localhost:8080/swagger-ui.html 訪問得到我們Swagger的組織結(jié)構(gòu)是

在上圖中我們了解到我們定義的控制層，得到的swagger生成的默認(rèn)結(jié)構(gòu)展示出來了。

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

在啟動類添加相關(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("獲取教某個學(xué)生的老師清單")
        @GetMapping("/his-teachers")
        public String ccc() {
            return "ccc";
        }
        @ApiOperation("創(chuàng)建一個學(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 {
    // ...
}

我們在Api的tags修改成為我們想要的表達(dá)文字：

合并Controller分組

在此，我們使用了Tag和Controller 一一對應(yīng)的情況，Swagger中還支持更加靈活的分組！從@Api注解中，我們?nèi)绻腥タ丛敿?xì)代碼的時候，發(fā)現(xiàn)tags屬性其實是一個數(shù)組類型。

因而，我們可以通過地定義同名的Tag來匯總Controller中的相關(guān)接口，比如我們可以定義一個Tag為“教學(xué)管理“，讓這個分組同時包含教師管理和學(xué)生管理的所有接口，案例如下：

@Api(tags = {"教師管理", "教學(xué)管理"})
@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
    // ...
}
@Api(tags = {"學(xué)生管理", "教學(xué)管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
    // ...
}

更新細(xì)粒度的接口分組

通過@Api可以實現(xiàn)將Controller中的接口合并到一個Tag中,但是如果我們希望精確到某個接口的合并，我們應(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("獲取教某個學(xué)生的老師清單")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }
    @ApiOperation("創(chuàng)建一個學(xué)生")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }
}

得到效果圖：

內(nèi)容的順序

在完成了接口的分組后，我們可以進(jìn)行對接口內(nèi)容的展示順序進(jìn)行調(diào)整，其中，我們主要涉及三個方面：分組的排序、接口的排序、以及參數(shù)的排序。

分組排序

關(guān)于分組排序，也就是Tag的排序。目前版本的Swagger支持并不太好，通過文檔我們可以找到關(guān)于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;
  }
}

我們可以發(fā)現(xiàn)Swagger 提供考慮一個選項，就是按照字字母順序進(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";
    }
    // ...
}

接口的排序

在完成了分組排序問題（雖然不太優(yōu)雅…）之后，在來看看同一分組內(nèi)各個接口該如何實現(xiàn)排序。同樣的，凡事先查文檔，可以看到Swagger也提供了相應(yīng)的配置，下面也分兩種配置方式介紹：
第一種還是適合原生Swagger用戶的，可以修改：

第二種：Swagger Starter用戶，可以通過修改配置方式：

swagger.ui-config.operations-sorter=alpha

這個配置不像Tag的排序配置沒有可選項。它提供了兩個配置項：alpha和method，分別代表了按字母表排序以及按方法定義順序排序。當(dāng)我們不配置的時候，改配置默認(rèn)為alpha。

參數(shù)的排序

完成了接口的排序后，更加細(xì)粒度的就是請求參數(shù)的排序了，在默認(rèn)的情況下，我們的Swagger會對Model的參數(shù)內(nèi)容展示進(jìn)行按照字母排序，我們的展示的User在Swagger之前是這樣的：

現(xiàn)在，我們希望可以按照Model中定義的成員變量順序來展示，那么需要我們通過@ApiModelProperty 注解的position參數(shù)來實現(xiàn)位置的設(shè)置。

對應(yīng)的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展示：