基于Swagger的资源分组实践

1. 概述

本文将探讨Java中Swagger文档的实用技巧，重点介绍如何通过URL路径对API进行分组。实现资源分组的方法有很多，但我们将聚焦于@Tag注解——这个通常放在控制器类顶部的利器。

2. 理解Swagger与`@Tag`注解

Swagger是个超实用的开源框架，能帮我们设计、构建、文档化和测试REST API。最棒的是它能自动生成文档，确保文档始终与API同步更新。

在Swagger（OpenAPI）体系中，标签（Tags）是分组和归类API操作的核心机制。具体来说，它提供了一种强大的方式来组织API文档，提升清晰度和可用性。

⚠️ 需要注意：标签可以在控制器类的类级别或方法级别定义。每个操作（GET/POST/PUT/DELETE）都可以关联一个或多个标签。

Swagger UI通常会将这些标签渲染为可折叠的分组，方便导航和理解。善用标签能显著改善API文档的结构和可访问性。

3. 搭建Spring Boot项目

开始前，我们需要一个带API的Spring Boot项目。

访问Spring Initializer，按以下参数配置项目：

项目：Maven
语言：Java
Spring Boot版本：3.4.4（或任意稳定版）
组：com.swaggertags
工件：demo
描述：Swagger标签演示项目
打包：Jar
JDK：17

spring setup

点击"Generate"下载项目，解压后添加必要依赖。

3.1. 添加Maven依赖

需要控制器来演示资源分组，先添加Web启动器依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

它提供了创建RESTful API所需的所有组件。

再添加Swagger依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.4.0</version>
</dependency>

这会为Spring Boot Web MVC应用集成Swagger/OpenAPI支持及友好界面。

4. 使用Swagger `@Tag`注解创建控制器

创建UserController，处理所有用户相关操作（URL以/api/users/开头）：

@RestController
@RequestMapping("/api/users/")
@Tag(name = "用户管理", description = "用户相关操作")
public class UserController {

    @PostMapping("login")
    public ResponseEntity<String> userLogin() {
        return ResponseEntity.ok("登录成功");
    }

    @Tag(name = "仪表盘")
    @GetMapping("profile")
    public ResponseEntity<String> getUserProfile() {
        return ResponseEntity.ok("用户资料");
    }

    @Tag(name = "仪表盘")
    @GetMapping("orders")
    public ResponseEntity<String> getUserOrders() {
        return ResponseEntity.ok("用户订单");
    }
}

解读注解：

@RestController：声明这是REST控制器
@RequestMapping：设置基础URL路径
@Tag：核心分组注解，name创建Swagger UI分组，description提供上下文说明

✅ 也可以在方法级别使用@Tag（如getUserOrders()）实现更细粒度分组。

再创建OrderController处理订单相关操作（URL以/api/orders开头）：

@RestController
@RequestMapping("/api/orders")
@Tag(name = "订单管理", description = "订单相关操作")
public class OrderController {

    @GetMapping
    public ResponseEntity<String> getAllOrders() {
        return ResponseEntity.ok("订单1");
    }
}

同样使用@Tag分组，但名称和描述不同，会生成独立分组。

4.1. 运行效果

启动应用，访问默认Swagger UI地址：http://localhost:8080/swagger-ui/index.html

展开后可见两个分组及其包含的接口：

output

5. 总结

Swagger（现属OpenAPI规范）是简化REST API设计、文档化和测试的利器。它能自动生成实时交互式文档，减少手动维护，确保文档与代码同步。

springdoc-openapi提供的@Tag注解是Spring Boot中组织API的关键：

在类/方法级别使用@Tag
将相关接口（如用户/订单操作）分组到Swagger UI的可折叠区块中
显著提升可读性、结构性和协作效率

只需少量配置（添加几个Maven依赖和控制器注解），就能获得结构清晰的Swagger UI，这对大型项目尤其友好。

本文代码可在GitHub获取

Persistence

REST

Security