通过 GroupedOpenApi 创建 API 分组。

示例代码

java复制代码import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("User Management") // 分组名称
                .pathsToMatch("/users/**") // 匹配的路径
                .build();
    }

    @Bean
    public GroupedOpenApi orderApi() {
        return GroupedOpenApi.builder()
                .group("Order Management") // 分组名称
                .pathsToMatch("/orders/**") // 匹配的路径
                .build();
    }
}

在上面的配置中：

• group("User Management") 定义了一个名为 "User Management" 的分组。
• pathsToMatch("/users/**") 表示将匹配路径 /users/** 的所有接口归入该分组。
• group("Order Management") 和 pathsToMatch("/orders/**") 定义了另一个分组。

---

4. 访问 Swagger UI

启动项目后，访问 http://localhost:8080/swagger-ui.html（默认端口为 8080），你会看到两个分组：

• User Management
• Order Management

每个分组中只会显示匹配对应路径的接口。

---

5. 高级用法

5.1 按包名分组

如果你想根据包名对 API 分组，可以使用 packagesToScan：

java复制代码@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
            .group("User Management")
            .packagesToScan("com.example.user") // 扫描指定包
            .build();
}

@Bean
public GroupedOpenApi orderApi() {
    return GroupedOpenApi.builder()
            .group("Order Management")
            .packagesToScan("com.example.order") // 扫描指定包
            .build();
}

• packagesToScan("com.example.user") 表示只扫描 com.example.user 包下的控制器。
• packagesToScan("com.example.order") 表示只扫描 com.example.order 包下的控制器。

5.2 使用路径排除规则

可以通过 pathsToExclude 来排除某些路径：

java复制代码@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("Admin API")
            .pathsToMatch("/admin/**") // 匹配 /admin/** 路径
            .pathsToExclude("/admin/secret/**") // 排除 /admin/secret/** 路径
            .build();
}

5.3 添加描述信息

可以为分组添加描述信息，方便在 Swagger UI 中查看。

java复制代码@Bean
public GroupedOpenApi productApi() {
    return GroupedOpenApi.builder()
            .group("Product Management")
            .pathsToMatch("/products/**")
            .addOpenApiCustomiser(openApi -> openApi.info(new io.swagger.v3.oas.models.info.Info()
                    .title("Product API")
                    .description("API for managing products")
                    .version("1.0")))
            .build();
}