Spring中如何用Swagger注解按资源分组API端点及多级分组？

我之前开发Spring REST API的时候也碰到过Swagger UI端点堆在一起、找起来头疼的情况，按资源分组绝对是提升可读性的关键操作，而且更高层级的重组也完全可以实现，下面给你具体的实现方案和示例：

一、用Swagger注解按资源级别分组端点 #

最直接的方式是给每个Controller添加@Api注解，通过tags属性指定资源分组名称，Swagger UI会自动把相同tag的端点归为一组。

示例代码： #

比如你有用户、订单、商品三个核心资源，对应的Controller可以这么写：

// 用户资源Controller
@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理") // 指定分组标签
public class UserController {
    @GetMapping
    @ApiOperation("获取所有用户列表")
    public List<User> getAllUsers() {
        // 业务逻辑
    }

    @GetMapping("/{id}")
    @ApiOperation("根据ID获取用户详情")
    public User getUserById(@PathVariable Long id) {
        // 业务逻辑
    }
}

// 订单资源Controller
@RestController
@RequestMapping("/api/orders")
@Api(tags = "订单管理") // 另一个分组标签
public class OrderController {
    @GetMapping
    @ApiOperation("获取当前用户的订单列表")
    public List<Order> getUserOrders() {
        // 业务逻辑
    }

    @PostMapping
    @ApiOperation("创建新订单")
    public Order createOrder(@RequestBody Order order) {
        // 业务逻辑
    }
}

这样配置后，Swagger UI里就会出现“用户管理”和“订单管理”两个分组，每个分组下对应各自的端点，界面一下子就清爽了。

二、更高层级的分组重组 #

如果你的资源分组还需要进一步归类（比如把“用户管理”“地址管理”归到“用户相关”大组，“订单管理”“支付管理”归到“交易相关”大组），可以通过GroupedOpenApi来实现（以SpringDoc为例，这是目前更主流的Swagger实现）。

示例代码： #

创建一个Swagger配置类，定义多个高层级分组：

@Configuration
public class SwaggerConfig {

    // 第一大组：用户相关
    @Bean
    public GroupedOpenApi userRelatedGroup() {
        return GroupedOpenApi.builder()
                .group("用户相关") // 大组名称
                .pathsToMatch("/api/users/**", "/api/addresses/**") // 匹配该组的接口路径
                .build();
    }

    // 第二大组：交易相关
    @Bean
    public GroupedOpenApi transactionRelatedGroup() {
        return GroupedOpenApi.builder()
                .group("交易相关") // 大组名称
                .pathsToMatch("/api/orders/**", "/api/payments/**") // 匹配该组的接口路径
                .build();
    }

    // 也可以按tags来分组，更灵活
    @Bean
    public GroupedOpenApi adminGroup() {
        return GroupedOpenApi.builder()
                .group("后台管理")
                .tagsToInclude("用户管理", "订单管理") // 包含指定标签的接口
                .build();
    }
}

配置完成后，Swagger UI顶部会出现分组选择下拉框，你可以切换不同的大组，每个大组下再展示对应的子资源分组，完美实现层级化的端点管理。

小提示 #

• 如果用的是旧版Springfox（Swagger 2），高层级分组可以用Docket的groupName属性来实现，思路类似。
• 标签名称尽量简洁统一，方便后续维护和查找。

这样调整后，你的Swagger UI就会层级清晰，不管有多少端点都能轻松找到啦～

内容的提问来源于stack exchange，提问作者Supun Wijerathne