Spring Boot 2.x based tutorial: Swagger Interface Classification and each element Detailed Scheduling

Before the adoption of Spring Boot 2.x Basics Tutorial: Using Swagger2 build powerful API documentation article, we learned how to use Swagger for the Spring Boot project is automatically generated API documentation, there are many users a message asking questions about the organization and content of the document sorting. So, open a special Swagger explain in detail how the document content is organized and how the various elements which control the specific configuration before and after the order.

Packet Interface

We define the interfaces is in the Spring Boot Controlleras the first stage dimension to the organization, Controllerthe relationship between the specific interface is one to many relationship. We can belong to the same interface definition in a module Controllerinside. By default, Swagger is Controllera unit of the interface to group management. This grouping of elements referred to in Swagger in Tag, but here's Tagrelationship with many of the interface is not that supports richer-many relationship.

Default grouping

First, we adopted a simple example, look at the default, Swagger is how to organize relations in accordance with the interface Tag Controller. Define two Controllerwere responsible for teacher management and student management interface, 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("获取学生清单")
    @GetMapping("/list")
    public String bbb() {
        return "bbb";
    }

    @ApiOperation("获取教某个学生的老师清单")
    @GetMapping("/his-teachers")
    public String ccc() {
        return "ccc";
    }

    @ApiOperation("创建一个学生")
    @PostMapping("/aaa")
    public String aaa() {
        return "aaa";
    }

}

After launching the application, we can see Swagger in both Controller is organized:

The markings of the generated default Swagger Tagwith Spring Boot the Controllercontent display position.

Custom name of the default packet

Then, we can try again by @Apinotes from the definition Tag, like this:

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

    // ...

}

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

    // ...

}

After launching the application again, we see the following contents of a packet, the code @Apidefined in tagsthe content replaces the default generated teacher-controllerand student-controller.

The combined group Controller

Here, we are just using Tagthe Controllersituation one correspondence, Swagger also support a more flexible packet! From @Apiproperty annotated, I believe clever readers will have found that tagsproperty is actually an array type:

We can define the same name Tagto the summary Controllerof the interface, for example, we can define a Tagas a "teaching management," so that this packet contains all the interfaces teacher management and student management, this can be achieved:

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

    // ...

}

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

    // ...

}

The final results are as follows:

More granular packet interface

By @Apimay achieve the Controllermerger of the interface into a Tagmedium, but if we want to be accurate to merge an interface it? For example, such a demand: "Teaching Management" contains "Teachers Management" "get a list of students' interfaces (not all Interface) interface and all" student management "management.

Then the above implementation can not be satisfied. Hair At this time, we can use @ApiOperationannotations in tagsmore fine grained interfaces classification defined attributes, such as the above requirements can be written like this:

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

}

Results as shown below:

Order content

After completion of the packet interfaces for order to show the contents of the interface point is of particular concern to many users, which mainly involves three aspects: Sort grouping, sorting and parameters of the interface, here we come one by one to talk about how to configure and use.

Packet sorting

About grouping and sorting, which is sort of Tag. The current version of Swagger support is not very good, we can find the document through configuration on Tag sorting.

The first: native Swagger user, by the following manner:

file

The second: Swagger Starter users can configure by modifying the way:

swagger.ui-config.tags-sorter=alpha

It seems to find hope, but in fact there is nothing this option, a look at the source code at a glance:

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

Yes, Swagger provides only one option, that is, in alphabetical order. So how do we achieve to sort it? Here you do not need to extend to a source, only rely on the definition of use to achieve the sort of suggestion: do number Tag name. such as:

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

    // ...

}

Since the original mechanism exists in alphabetical increase in numbers to help sort by name, a simple and brutal grouping solve the problem, the final effect is as follows:

Sort Interface

In (although not elegant ...) After completing the packet scheduling problem, take a look at how the various interfaces within the same group to achieve the sort. Similarly, where a document check in advance, you can see Swagger also provides a corresponding configuration, the following description can be divided in two configurations:

The first: native Swagger user, by the following manner:

The second: Swagger Starter users can configure by modifying the way:

swagger.ui-config.operations-sorter=alpha

I am happy that this configuration is not unlike Tag sort of configuration options. It provides two configuration items: alphaand method, respectively, represent sorted in alphabetical order and is defined by the method. When we are not configured to change the default configuration alpha. Compare two effects configuration as shown below:

Sorting parameters

After completion of the ordering interface is finer grained request the sequencing of the parameters. By default, Swagger Model parameters for presentation of content are arranged in alphabetical order. So before the tutorial User object in the article to show the following:

If we want to be in accordance with the member variables defined in order to show the Model, then we need to pass @ApiModelPropertyannotations positionto achieve the set location parameters, such as:

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

}

The final results are as follows:

summary

This article describes in detail the organization control over the interface Swagger content. Some issues are not addressed by configuration, it may be to understand the content of the document or the source code is not deep enough. If readers have a better implementation, and welcome exchange.

The sample code

The complete works of this paper can be viewed below repository chapter2-4directory:

If you think this article is good, welcome Star support, your concern is I insist on the power!

Relevant information

I welcome the attention of the public number: Program ape DD, get exclusive organize learning resources and push dry goods daily.
If you are interested in my topic content, you can focus on my blog: didispace.com