1. 项目概述：为什么我们需要关注Swagger2的多级分组？

在微服务架构和前后端分离成为主流的今天，API文档的清晰度和可维护性直接关系到团队的开发效率。Swagger2（现在更常指Springfox或Springdoc OpenAPI）作为Java生态中事实上的API文档标准，其默认的、将所有接口平铺展示的方式，在项目接口数量达到几十甚至上百个时，就会变得难以管理。想象一下，一个大型电商后台管理系统，用户管理、商品中心、订单服务、营销活动、数据统计等模块的接口全部混在一起，前端开发同学想找一个“修改用户收货地址”的接口，可能需要滚动屏幕半天，还得在一堆命名相似的接口里仔细甄别。这不仅浪费时间，更容易在联调时引发错误。

这就是“Swagger2接口多级分组”要解决的核心痛点。它不是一个简单的UI美化功能，而是一种基于业务逻辑和团队协作模式的文档组织策略。通过多级分组，我们可以将接口按照业务模块、版本号、甚至是团队职责进行清晰的层级划分，让文档结构一目了然。对于后端开发者，这意味着更规范的代码组织；对于前端、测试以及任何需要调用API的协作者，这意味着更高效的沟通和更低的认知成本。我经历过从“一锅粥”式的文档到结构化文档的转变，实测下来，一个清晰的分组能为一个中型项目每周节省数小时的沟通时间，并且显著减少因调用错误接口而导致的线上问题。

2. 核心思路与方案选型：从“能用”到“好用”的进化

实现Swagger2的多级分组，本质上是在引导Swagger的Docket（文档配置实例）和API扫描机制，按照我们设定的规则去组织和呈现接口。市面上常见的方法大致可以分为三类，每种都有其适用场景和优缺点。

2.1 方案一：基于包路径（Package）的分组

这是最直观、也是最容易上手的方法。其核心思想是：一个Docket实例只扫描一个或多个特定的Java包路径，每个包（或包集合）对应Swagger UI中的一个分组标签（Tag）。

为什么选择它？

  • 天然映射业务模块 ：在良好的项目架构中， com.xxx.user.controller 、 com.xxx.order.controller 这样的包名本身就代表了业务模块。基于此分组，文档结构与代码结构高度一致，便于维护。
  • 配置简单，侵入性低 ：只需要在配置类中创建多个Docket Bean，分别指定不同的 apis(RequestHandlerSelectors.basePackage(“…”)) 即可。无需修改任何业务Controller代码。
  • 适合中大型项目模块化拆分 ：当你的服务已经按照领域进行分包，这种方法几乎是零成本的文档结构化方案。

实操中的取舍点 ： 这种方式假设你的代码结构是完美的。但如果你的项目历史包袱重，或者存在跨模块的公共接口，就需要更灵活的扫描策略，比如结合注解选择器。

2.2 方案二：基于自定义注解的分组

这是一种更灵活、更强调“契约”的分组方式。我们自定义一个注解，例如 @ApiModule(name = “用户中心”， version=“1.0”) ，然后在每个Controller类上标记它。在配置Docket时，通过 apis(RequestHandlerSelectors.withClassAnnotation(ApiModule.class)) 来筛选。

为什么选择它？

  • 解耦文档分组与代码物理结构 ：一个Controller即使放在 common 包下，只要打了 @ApiModule(name=“营销”) 注解，它就会被归入营销分组。这特别适合处理那些服务于多个业务线的通用接口。
  • 支持多维分组 ：注解可以定义多个属性，比如 module 和 version 。你可以创建两个Docket，一个按 module 扫描，另一个按 version 扫描，从而在Swagger UI上实现“模块”和“版本”两个维度的标签页切换，这是包路径分组难以实现的。
  • 声明式配置，意图清晰 ：在Controller类上看到这个注解，开发者立刻就能明白这个接口所属的业务范畴，起到了文档注释的作用。

需要注意的坑 ： 灵活性带来了一定的复杂度。你需要维护这个自定义注解，并且确保团队成员都遵守规范进行标记。如果漏标，对应的接口就会“消失”在文档中。

2.3 方案三：混合策略与高级定制

在实际的大型项目中，我们往往不会只采用单一策略，而是“包路径为主，注解为辅”的混合模式。

典型场景 ：

  1. 主体按包分组 ：为 user ， order ， product 等核心模块创建主要Docket。
  2. 特殊接口用注解归集 ：例如，所有模块都需要暴露的“数据导出”接口，分散在各个Controller中。我们可以为这些方法添加一个 @ApiExport 自定义注解，然后单独配置一个名为“数据导出服务”的Docket来扫描所有带有此注解的方法，将它们聚合在一起。
  3. 利用 @Api 注解的tags属性 ：Swagger原生的 @Api 注解有一个 tags 属性，可以为Controller指定标签。我们可以在Docket配置中，通过 groupName 和 tags 的配合，实现更精细的展示控制。但请注意， tags 更多是用于在同一个分组内进行二次分类（在UI上通常表现为可折叠的节点），而非创建顶级分组标签。

方案选型建议 ：

  • 初创或中小型项目 ：直接采用 方案一（包路径分组） ，简单有效，快速收益。
  • 中大型或架构复杂的项目 ：采用 方案三（混合策略） 。先以包路径建立主干分组，再针对交叉、通用功能使用自定义注解创建辅助分组。
  • 当需要实现“版本化API文档”等特殊需求时 ： 方案二（注解分组） 的优势就凸显出来了，可以为v1、v2等不同版本创建独立的分组和Docket。

提示：无论选择哪种方案，请务必在团队内部建立并遵守统一的规范。分组的最终目的是为了提效，混乱的分组规则比没有分组更糟糕。

3. 核心细节解析与实操要点

理解了思路，我们进入实战环节。这里以最常用的Spring Boot + Springfox Swagger2为例，详细拆解每一步。我会假设一个电商后台项目，包含用户、订单、商品三个核心模块。

3.1 环境准备与依赖确认

首先，确保你的 pom.xml 中包含了正确的依赖。Springfox有两套主流方案，注意区分： 

<!-- 方案A: Springfox Swagger2 (较老，已停止维护，但存量项目多) -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version> <!-- 请使用最终稳定版 -->
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- 方案B: Springdoc OpenAPI (官方推荐，兼容OpenAPI 3.0，活跃维护) -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version> <!-- 请查看最新版本 -->
</dependency>

本文主要基于 Springfox Swagger2 进行讲解，因为其配置方式对“分组”这个概念更显式。Springdoc OpenAPI的分组思路类似，但配置项和注解略有不同，文末会给出简要对比。

关键检查点 ：

  • 确认Spring Boot版本与Springfox的兼容性。Spring Boot 2.6+版本由于路径匹配策略变更，与Springfox 2.x存在兼容性问题，可能需要额外配置或考虑迁移到Springdoc。
  • 如果使用Spring Security，需要放行Swagger相关的资源路径（ /swagger-resources/** ， /v2/api-docs ， /swagger-ui.html 等），否则无法访问文档页面。

3.2 基础配置类与单Docket模式

在开始多分组前，先看看标准单分组配置，以理解核心组件。 

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 指定扫描的包路径，这是分组的核心入口
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("电商后台API文档")
                .description("这是一个简单的描述")
                .version("1.0")
                .build();
    }
}

这里的 Docket 对象就是一份文档的生成器。 RequestHandlerSelectors.basePackage() 定义了它的扫描范围。多分组的本质，就是创建多个 Docket Bean，并为每个Bean赋予不同的扫描规则和组名。

3.3 多Docket配置实战：基于包路径的分组

现在，我们来创建三个分组：用户、订单、商品。 

@Configuration
@EnableSwagger2
public class MultiGroupSwaggerConfig {

    /**
     * 用户模块API分组
     */
    @Bean
    public Docket userApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户中心") // 关键：设置分组名称，将在UI下拉框/标签页显示
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ecommerce.user.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 订单模块API分组
     */
    @Bean
    public Docket orderApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("订单服务")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ecommerce.order.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 商品模块API分组
     */
    @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("商品管理")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ecommerce.product.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        // 可以统一，也可以为不同分组定制不同的ApiInfo
        return new ApiInfoBuilder()
                .title("电商后台管理系统API文档")
                .description("本文档包含用户、订单、商品等模块的接口说明")
                .version("2.0")
                .build();
    }
}

启动应用，访问 http://localhost:8080/swagger-ui.html 。在页面右上角，你会看到一个下拉选择框，里面列出了“用户中心”、“订单服务”、“商品管理”三个选项。选择其中一个，页面将只展示该分组下的接口。这就实现了最基础的多级（在这里是并列一级）分组。

实操心得 ：

  • groupName 必须唯一 ，否则后定义的Bean会覆盖先定义的。
  • 可以为不同的分组配置不同的 apiInfo ，比如版本号、联系人信息等，使文档更精确。
  • paths(PathSelectors.any()) 是路径过滤器，你可以使用 PathSelectors.regex(“/api/v1/.*”) 来只匹配特定路径规则的接口，实现基于URL前缀的版本分组。

3.4 进阶：基于自定义注解的混合分组

假设我们有一个“数据看板”功能，需要从用户、订单、商品模块中各抽取一个统计接口，聚合展示。我们不想破坏原有的包分组，又想提供一个统一的“数据看板”视图。

第一步：定义自定义注解 

@Target({ElementType.TYPE, ElementType.METHOD}) // 可以标注在类或方法上
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiDashboard {
    String value() default "";
}

第二步：在需要暴露的统计方法上标记注解 

// 在 UserController.java 中
@RestController
@RequestMapping("/user")
public class UserController {
    // ... 其他用户接口

    @ApiOperation(“用户增长统计”)
    @GetMapping("/stats/growth")
    @ApiDashboard // 标记此接口属于数据看板
    public Result userGrowthStats() {
        // ...
    }
}

// 在 OrderController.java 中
@RestController
@RequestMapping("/order")
public class OrderController {
    @ApiOperation(“订单成交额统计”)
    @GetMapping("/stats/amount")
    @ApiDashboard // 标记此接口属于数据看板
    public Result orderAmountStats() {
        // ...
    }
}

第三步：配置一个独立的Docket来扫描这个注解 

@Configuration
@EnableSwagger2
public class MixedSwaggerConfig {

    // ... 之前基于包路径的 userApi, orderApi, productApi Bean 保持不变 ...

    /**
     * 数据看板API分组 (基于注解)
     */
    @Bean
    public Docket dashboardApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(“数据看板”)
                .apiInfo(apiInfo())
                .select()
                // 关键：选择所有带有 @ApiDashboard 注解的处理器（类或方法）
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiDashboard.class))
                .paths(PathSelectors.any())
                .build();
    }
}

现在，Swagger UI的下拉框中会多出一个“数据看板”分组。点进去，你会看到来自不同Controller的、被打上 @ApiDashboard 注解的所有统计接口，完美实现了跨模块的接口聚合。

4. 实操过程与核心环节实现

让我们构建一个更复杂的场景，模拟一个微服务架构下的配置。假设我们有一个主应用，集成了两个内部客户端模块的API文档。

4.1 场景设定与项目结构

  • 主工程 ： ecommerce-platform ，端口8080。
  • 用户服务客户端模块 ： user-service-client ，作为一个Jar包被主工程依赖，其Controller在 com.platform.user.client.controller 包下。
  • 商品服务客户端模块 ： product-service-client ，同样作为Jar包依赖，Controller在 com.platform.product.client.controller 包下。
  • 目标 ：在主工程的Swagger文档中，清晰展示“平台自身接口”、“用户服务接口”、“商品服务接口”三个分组。

4.2 统一配置类的编写

在主工程的配置类中，我们需要扫描来自不同模块（即不同Jar包）的特定包路径。 

@Configuration
@EnableSwagger2
public class PlatformSwaggerConfig {

    @Bean
    public Docket platformApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(“平台管理”)
                .apiInfo(apiInfo())
                .select()
                // 扫描主工程自身的Controller
                .apis(RequestHandlerSelectors.basePackage(“com.ecommerce.platform.controller”))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket userServiceApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(“用户服务”)
                .apiInfo(apiInfo())
                .select()
                // 扫描来自user-service-client模块的包
                .apis(RequestHandlerSelectors.basePackage(“com.platform.user.client.controller”))
                .paths(PathSelectors.any())
                .build()
                // 可选：为客户端接口添加全局标签或参数
                .tags(new Tag(“用户服务”, “所有用户相关的远程调用接口”));
    }

    @Bean
    public Docket productServiceApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(“商品服务”)
                .apiInfo(apiInfo())
                .select()
                // 扫描来自product-service-client模块的包
                .apis(RequestHandlerSelectors.basePackage(“com.platform.product.client.controller”))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(“电商平台聚合API文档”)
                .description(“整合平台自身功能及用户、商品微服务接口”)
                .version(“1.0”)
                .contact(new Contact(“平台团队”, “https://internal.team.com”, “platform@company.com”))
                .build();
    }
}

4.3 使用 @Api 注解进行组内细分

有时，一个分组内接口很多，我们希望在分组内再进行分类。这时可以使用Swagger原生的 @Api 注解的 tags 属性。 

// 在 UserController.java 中
@RestController
@RequestMapping(“/user”)
@Api(tags = {“用户基础信息”, “客户端接口”}) // 定义该Controller下所有接口的标签
public class UserClientController {

    @ApiOperation(“获取用户详情”)
    @GetMapping(“/{id}”)
    public UserDTO getUser(@PathVariable Long id) {
        // ...
    }

    @ApiOperation(“批量查询用户”)
    @PostMapping(“/batch”)
    public List<UserDTO> getUsers(@RequestBody List<Long> ids) {
        // ...
    }
}

// 在 UserAuthController.java 中 (同一个包下)
@RestController
@RequestMapping(“/user/auth”)
@Api(tags = {“用户认证授权”, “客户端接口”}) // 同一个分组下，不同的标签
public class UserAuthClientController {
    @ApiOperation(“用户登录”)
    @PostMapping(“/login”)
    public Token login(@RequestBody LoginVO vo) {
        // ...
    }
}

当你在Swagger UI中选择“用户服务”分组后，页面内会显示“用户基础信息”和“用户认证授权”两个可展开/折叠的标签区域，实现了分组内的二级结构。这比纯粹平铺的接口列表要清晰得多。

核心环节总结 ：

  1. 定义清晰的包结构 是分组的基础，规划好Controller的存放位置。
  2. 创建多个 Docket Bean ，每个Bean代表一个独立的分组。
  3. **为每个 Docket 设置唯一的 groupName **和精确的 apis 扫描规则（包路径或注解）。
  4. **善用 @Api(tags=) **进行组内接口的二次分类，提升文档可读性。
  5. 考虑微服务场景 ，通过扫描依赖模块的包路径来聚合多个服务的API。

5. 常见问题与排查技巧实录

在实际配置和使用的过程中，你肯定会遇到一些坑。下面是我和团队踩过之后总结出来的常见问题及解决方案。

5.1 问题一：配置了多个Docket，但Swagger UI上只显示一个分组或下拉框不出现

排查步骤 ：

  1. 检查Bean名称与 groupName ：确保每个 @Bean 方法返回的 Docket 对象都有 唯一 的 groupName 。如果重复，后者会覆盖前者。Bean的方法名本身不重要，重要的是 groupName 。
  2. 检查扫描路径是否重叠或为空 ：如果两个Docket的扫描路径（ basePackage ）有重叠，同一个接口可能会出现在多个分组，但UI通常仍会显示多个分组选项。如果某个Docket的扫描路径下没有任何Controller，则该分组会被创建，但点进去是空的，下拉框依然存在。
  3. 确认依赖和注解 ：确保 @Configuration 和 @EnableSwagger2 注解已正确添加到配置类上。检查Springfox Swagger2的依赖是否被正确引入，且没有版本冲突。
  4. 查看启动日志 ：Springfox在启动时会打印注册了哪些Docket。搜索日志中的“Swagger2Controller”或“Docket”相关字样，确认你的多个Bean是否都被初始化。

根本原因 ：绝大多数情况都是 groupName 重复导致的静默覆盖。

5.2 问题二：接口的Model（实体类）说明在分组后丢失或不完整

现象 ：在默认分组或某个分组下，接口的请求/响应参数实体类显示为泛型的 Object 或 Model ，没有展开字段详情。

原因与解决 ： Swagger的Model扫描默认是全局的，但有时在多模块或复杂依赖下会出问题。确保你的实体类（DTO/VO）也被Swagger扫描到。

  1. 显式指定Model扫描包 ：在创建Docket时，使用 .additionalModels 方法手动添加，但这种方式繁琐。
  2. 更优方案：确保实体类在扫描路径内或可被访问 ：Swagger通过 @ApiModel 等注解来识别模型。最可靠的方式是，将公共的实体类放在一个独立的模块（如 common-model ）中，并确保这个模块被主项目依赖。同时，在Docket配置中，可以尝试扩大 apis 的扫描范围，或者使用 RequestHandlerSelectors.any() 临时测试，看模型是否能正常显示。如果显示正常，再逐步缩小扫描范围定位问题。
  3. 检查Jackson注解 ：Swagger也依赖Jackson的 @JsonProperty 、 @JsonIgnore 等注解来生成字段描述。确保你的实体类序列化配置正确。

5.3 问题三：分组的排序或自定义显示

需求 ：希望“订单服务”分组显示在第一个，或者想为分组添加更详细的描述。

解决方案 ： Springfox的UI分组下拉框默认按Bean的注册顺序（或字母顺序？）显示，控制力较弱。如果需要对UI进行深度定制，有以下途径：

  1. 实现 SwaggerResourcesProvider 接口 ：这是更底层的控制方式。你可以自定义这个Bean的 get() 方法，返回一个 SwaggerResource 列表，在这个列表里你可以完全控制每个分组（对应一个 SwaggerResource ）的名称、位置、排序以及对应的 /v2/api-docs 端点地址。这种方式功能强大，但复杂度较高。
  2. 使用 springfox-swagger-ui 的定制化 ：你可以覆盖默认的Swagger UI页面，通过自定义JavaScript来控制UI的渲染逻辑，包括分组排序。这需要前端知识。
  3. 妥协方案：通过Bean定义顺序控制 ：在 @Configuration 类中，按你想要的顺序定义 @Bean 方法。虽然Spring不保证严格的加载顺序，但在简单场景下通常有效。更稳妥的是使用 @DependsOn 注解，但用于分组排序显得太重。

个人建议 ：对于大多数项目，接受默认的排序（通常是Bean名称的字母顺序）即可。保持配置类中Bean定义的逻辑顺序（如核心业务在前，辅助功能在后），通常能达到可接受的效果。不必为了完美的排序而引入过度的复杂度。

5.4 问题四：从Springfox迁移到Springdoc OpenAPI

背景 ：Springfox 2.x已停止维护，Spring Boot 2.6+官方建议使用Springdoc OpenAPI。

分组概念对比 ： 在Springdoc中，没有直接的 Docket 和 groupName 概念。取而代之的是“分组”通过定义多个 GroupedOpenApi Bean来实现。

Springdoc多分组配置示例 ： 

@Configuration
public class SpringDocConfig {

    @Bean
    public GroupedOpenApi platformApi() {
        return GroupedOpenApi.builder()
                .group(“平台管理”) // 分组名称
                .pathsToMatch(“/platform/**”) // 通过路径匹配
                // .packagesToScan(“com.ecommerce.platform.controller”) // 或通过包扫描
                .build();
    }

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group(“用户服务”)
                .pathsToMatch(“/user/**”)
                .build();
    }

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title(“电商平台API”).version(“1.0”));
    }
}

迁移注意点 ：

  1. 注解从 @Api 、 @ApiOperation 等（io.swagger.annotations包）换成了 @Operation 、 @Tag 等（io.swagger.v3.oas.annotations包）。依赖需要改为 springdoc-openapi-ui 。
  2. Springdoc默认访问地址是 http://localhost:8080/swagger-ui.html （与Springfox相同），但API文档的JSON端点变为了 /v3/api-docs/{group} ，其中 {group} 是你的分组名。
  3. Springdoc的功能更强大，对OpenAPI 3.0规范的支持更完善，且社区活跃。新项目建议直接使用Springdoc。

6. 性能考量与生产环境建议

在本地开发环境，Swagger的配置怎么方便怎么来。但在生产环境，我们需要更加谨慎。

6.1 控制扫描范围，提升启动速度

RequestHandlerSelectors.any() 会扫描所有Controller，包括Spring Boot自带的 BasicErrorController 等。在生产配置中，应该使用更精确的 basePackage 或 withClassAnnotation 来限定范围，减少不必要的扫描和模型解析时间，这对大型应用启动速度有积极影响。

6.2 生产环境禁用Swagger UI

绝对不要 将包含Swagger UI的依赖直接部署到生产服务器。它暴露了所有的API接口信息，是严重的安全隐患。

标准做法 ：

  1. 使用Maven Profiles或Spring Profiles ： 
    <!-- pom.xml -->
<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <dependencies>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>
        </dependencies>
    </profile>
    <profile>
        <id>prod</id>
        <dependencies>
            <!-- 生产环境不引入swagger-ui -->
        </dependencies>
    </profile>
</profiles>
  2. 在配置类上使用 @Profile 注解 ： 
    @Configuration
@EnableSwagger2
@Profile({“dev”, “test”}) // 仅在dev和test环境生效
public class SwaggerConfig {
    // ...
}
  3. 使用 springfox.documentation.enabled 配置项 ：在 application-prod.yml 中设置 springfox.documentation.enabled=false ，可以完全禁用Swagger的自动配置。

6.3 生成离线文档

对于需要交付给外部团队或作为项目存档的文档，可以考虑在构建阶段生成离线的OpenAPI规范文件（JSON/YAML）。

使用Maven插件 （以Springdoc为例）： 

<plugin>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-maven-plugin</artifactId>
    <version>1.4</version>
    <executions>
        <execution>
            <phase>integration-test</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <apiDocsUrl>http://localhost:${server.port}/v3/api-docs</apiDocsUrl>
                <outputFileName>openapi.json</outputFileName>
                <outputDir>${project.build.directory}/api-docs</outputDir>
            </configuration>
        </execution>
    </executions>
</plugin>

运行 mvn integration-test 后，即可在target目录下生成 openapi.json 文件。这个文件可以被导入到Postman、Apifox等API工具，或者用于生成静态HTML文档。

7. 扩展思考：超越基础分组

当你熟练掌握了基础的多级分组后，可以思考一些更进阶的玩法，让API文档真正成为团队高效的利器。

按API版本分组 ：这是一个非常实用的场景。你可以为 /api/v1/** 和 /api/v2/** 路径分别创建两个Docket。这样，前端可以清晰地看到不同版本的接口，并行开发和迁移时非常方便。配置的关键在于 paths(PathSelectors.regex(“/api/v1/.*”)) 。

按访问权限分组 ：例如，将接口分为“公开API”、“内部API”、“管理后台API”。这可以通过结合自定义注解（如 @InternalApi ）和不同的Docket扫描来实现。更进一步，可以配合Spring Security，在配置类中根据当前用户的权限动态决定哪些分组可见（但这需要更深入的定制Swagger的配置解析过程）。

与API网关集成 ：在微服务架构下，每个服务都有自己的Swagger文档。你可以在API网关层（如Spring Cloud Gateway）集成一个聚合的Swagger UI，它通过调用各个服务的 /v2/api-docs 端点，将文档动态聚合起来。这时，每个服务定义的 groupName 就会成为网关聚合页面上的一个个标签页。常见的开源组件如 swagger-aggregator 或 springdoc-openapi 的网关支持模块可以简化这个工作。

文档即契约，驱动开发 ：清晰的分组是推动“契约先行”开发模式的好帮手。在项目初期，后端可以先定义出各个分组的接口契约（使用Swagger注解描述），生成文档。前端即可据此并行开发Mock数据。分组使得这份初始契约结构清晰，易于评审和讨论。

从我个人的经验来看，花一点时间规划并实施Swagger的多级分组，是一项投入产出比极高的基础设施投资。它强迫团队去思考接口的边界和归属，无形中促进了代码结构的优化。当新同事加入项目，一份结构清晰的API文档就是他最快上手的路线图。当进行系统重构或模块拆分时，现有的分组也是重要的依赖关系参考。说到底，好的文档不是写出来的，而是通过像分组这样的好习惯，从代码中自然生长出来的。

# 微服务
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

智能物联网场景下，支持多模型的AI平台实际表现解析

avatar 亚马逊云科技技术品牌专区
cover

基于大数据+Hadoop+深度学习的淘宝用户购物可视化与行为预测系统设计与开发

avatar 亚马逊云科技技术品牌专区
cover

空间智能场景下，AI算力成本优化的核心路径与平台选型

avatar 亚马逊云科技技术品牌专区