Spring应用中配置多个独立Swagger UI页面的实现方法咨询

我之前也遇到过类似的需求——默认的Swagger UI分组切换满足不了独立页面的要求，下面是亲测可行的实现步骤，分Springfox（Swagger 2）和SpringDoc（OpenAPI 3）两种方案，你可以根据自己的技术栈选择：

方案一：基于Springfox（Swagger 2） #

1. 配置两个独立的Docket实例 #

首先定义两个Docket Bean，分别对应订单和库存模块的API分组，指定不同的包路径和分组名：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    // 订单模块API配置
    @Bean
    public Docket orderApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("order-api") // 唯一分组名
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourproject.order")) // 订单模块的根包
                .paths(PathSelectors.any())
                .build()
                .apiInfo(buildApiInfo("订单服务API", "订单模块RESTful API文档"));
    }

    // 库存模块API配置
    @Bean
    public Docket inventoryApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("inventory-api") // 唯一分组名
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yourproject.inventory")) // 库存模块的根包
                .paths(PathSelectors.any())
                .build()
                .apiInfo(buildApiInfo("库存服务API", "库存模块RESTful API文档"));
    }

    // 封装API基础信息
    private ApiInfo buildApiInfo(String title, String description) {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .version("1.0.0")
                .build();
    }
}

2. 创建独立的Swagger UI页面 #

默认的swagger-ui.html只能加载所有分组的下拉选项，所以我们需要自定义两个HTML页面，分别绑定对应的分组API文档：

• 在src/main/resources/static目录下创建order-swagger.ui.html，内容如下：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>订单服务Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="webjars/swagger-ui/3.52.5/swagger-ui.css" />
    <link rel="icon" type="image/png" href="webjars/swagger-ui/3.52.5/favicon-32x32.png" sizes="32x32" />
    <style>
        html { box-sizing: border-box; overflow-y: scroll; }
        *, *:before, *:after { box-sizing: inherit; }
        body { margin: 0; background: #fafafa; }
    </style>
</head>
<body>
<div id="swagger-ui"></div>
<script src="webjars/swagger-ui/3.52.5/swagger-ui-bundle.js"></script>
<script src="webjars/swagger-ui/3.52.5/swagger-ui-standalone-preset.js"></script>
<script>
    window.onload = function() {
        // 绑定订单分组的API文档地址
        const ui = SwaggerUIBundle({
            url: "/v2/api-docs?group=order-api",
            dom_id: '#swagger-ui',
            deepLinking: true,
            presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
            plugins: [SwaggerUIBundle.plugins.DownloadUrl],
            layout: "StandaloneLayout"
        })
        window.ui = ui
    }
</script>
</body>
</html>

• 同理创建inventory-swagger.ui.html，只需要把url参数改成"/v2/api-docs?group=inventory-api"即可。

3. 测试访问 #

启动应用后，直接访问：

• 订单模块：http://localhost:8080/order-swagger.ui.html
• 库存模块：http://localhost:8080/inventory-swagger.ui.html

方案二：基于SpringDoc（OpenAPI 3，推荐） #

由于Springfox已停止维护，如果你用的是Spring Boot 2.2+，更推荐使用SpringDoc：

1. 配置分组API #

@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi orderApi() {
        return GroupedOpenApi.builder()
                .group("order-api")
                .packagesToScan("com.yourproject.order")
                .build();
    }

    @Bean
    public GroupedOpenApi inventoryApi() {
        return GroupedOpenApi.builder()
                .group("inventory-api")
                .packagesToScan("com.yourproject.inventory")
                .build();
    }
}

2. 创建独立UI页面 #

同样在src/main/resources/static下创建两个HTML文件，区别是API文档地址换成OpenAPI的路径：

• order-swagger.ui.html中url改为"/v3/api-docs?group=order-api"
• inventory-swagger.ui.html中url改为"/v3/api-docs?group=inventory-api"

3. 依赖说明 #

确保你的pom.xml中引入了SpringDoc依赖（对应Spring Boot 2.x）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

如果是Spring Boot 3.x，使用springdoc-openapi-starter-webmvc-ui依赖。

关键注意点 #

• 确保两个Docket/GroupedOpenApi的groupName唯一，否则会覆盖
• 自定义HTML中的webjars版本要和你的依赖版本一致，避免资源加载失败
• 如果你的应用有静态资源拦截配置，要确保这些HTML文件能被正常访问

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