Spring Boot 2.x基礎教程：Swagger接口分類與各元素排序問題詳解

以前經過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-controller和student-controller。

合併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;

}複製代碼

最終效果以下：

小結

本文詳細的介紹了Swagger中對接口內容的組織控制。有些問題並無經過配置來解決，也多是對文檔或源碼內容的瞭解不夠深刻。若是讀者有更好的實現方案，歡迎提出與交流。

代碼示例

本文的完整工程能夠查看下面倉庫中的chapter2-4目錄：

• Github：github.com/dyc87112/Sp…
• Gitee：gitee.com/didispace/S…

若是您以爲本文不錯，歡迎Star支持，您的關注是我堅持的動力！

相關資料

• swagger.io/docs/
• blog.didispace.com/spring-boot…
• github.com/SpringForAl…

本文首發：blog.didispace.com/spring-boot…

歡迎關注個人公衆號：程序猿DD，得到獨家整理的學習資源和平常乾貨推送。

若是您對個人專題內容感興趣，也能夠關注個人博客：didispace.com