Master Swagger API Documentation: Organize, Group, and Sort Endpoints in Spring Boot

In the previous Spring Boot 2.x tutorial we learned how to generate API documentation automatically with Swagger; this article dives deeper into how to organize the documentation content, control the order of groups, interfaces, and parameters, and customize tag names.

Interface Grouping

Swagger groups APIs by Controller as the primary dimension, using Tag to represent each group. By default, each Controller maps to a single Tag, but the @Api annotation can define custom tag names.

Default Grouping

Two controllers, one for teacher management and one for student management, are automatically grouped by their controller names:

@RestController
@RequestMapping(value = "/teacher")
static class TeacherController {
    @GetMapping("/xxx")
    public String xxx() { return "xxx"; }
}

@RestController
@RequestMapping(value = "/student")
static class StudentController {
    @ApiOperation("Get student list")
    @GetMapping("/list")
    public String bbb() { return "bbb"; }
    @ApiOperation("Get teachers of a student")
    @GetMapping("/his-teachers")
    public String ccc() { return "ccc"; }
    @ApiOperation("Create a student")
    @PostMapping("/aaa")
    public String aaa() { return "aaa"; }
}

The generated Swagger UI shows tags corresponding to the two controllers.

Custom Tag Names

Using @Api(tags = "Teacher Management") and @Api(tags = "Student Management") replaces the default tag names:

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

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

The UI now displays the custom tag names.

Merging Controller Groups

By assigning the same tag to multiple controllers, you can merge them into a single group. For example, adding the tag 教学管理 to both controllers groups all related endpoints together.

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

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

Fine‑Grained Interface Grouping

To group specific operations, use the tags attribute of @ApiOperation. For instance, only the "Get student list" operation can belong to the 教学管理 tag while the controller remains under 学生管理.

@Api(tags = {"学生管理"})
@RestController
@RequestMapping(value = "/student")
static class StudentController {
    @ApiOperation(value = "获取学生清单", tags = "教学管理")
    @GetMapping("/list")
    public String bbb() { return "bbb"; }
    // other methods
}

Content Order

After grouping, you may want to control the order of tags, operations, and parameters.

Tag Sorting

Swagger only supports alphabetical sorting. To achieve a custom order, prepend numbers to tag names, e.g., 1-教师管理, 2-学生管理, 3-教学管理.

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

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

Operation Sorting

Swagger provides two sorter options: alpha (alphabetical) and method (declaration order). Configure via swagger.ui-config.operations-sorter=alpha or method.

Parameter Sorting

Model fields are displayed alphabetically by default. Use @ApiModelProperty(position = n) to define the display order of fields in the generated documentation.

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

Summary

This article provides a comprehensive guide to organizing Swagger API documentation in Spring Boot, covering default and custom tag grouping, merging groups, fine‑grained operation tags, and sorting of tags, operations, and model parameters.

Code Example Repository

GitHub: https://github.com/dyc87112/SpringBoot-Learning/tree/2.x

Gitee: https://gitee.com/didispace/SpringBoot-Learning/tree/2.x

Related Resources

Swagger Official Documentation

Spring Boot Learning Blog

Spring Boot Starter Swagger