如何用Swagger2为两个Spring Boot项目生成集中式文档（非Maven多模块）

阿华AIGC实验室

2026-5-21

Swagger2实现多Spring Boot项目集中式文档的方案

一、可行性说明

完全可以用Swagger2实现！Swagger2的核心逻辑是让每个Spring Boot服务通过/v2/api-docs接口输出API元数据（JSON格式），我们只需要一个聚合入口来拉取并统一展示这些元数据，就能实现集中式的文档管理，完全不需要依赖Maven多模块结构。

二、非Maven多模块的可行方案

1. 独立Swagger聚合服务

单独搭建一个轻量的Spring Boot项目作为文档聚合中心，完全不侵入原有A、B项目的代码，步骤如下：

给聚合项目引入和A、B一致的Swagger2依赖
在配置类中配置多个Swagger资源，指向A、B项目的/v2/api-docs地址
启动聚合服务后，访问它的/swagger-ui.html就能切换查看A、B的所有API

示例配置代码：

@Configuration
@EnableSwagger2
public class SwaggerAggregationConfig {

    // 配置聚合文档的基础信息
    @Bean
    public Docket aggregatedApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("项目A+B聚合文档")
                .apiInfo(apiInfo());
    }

    // 配置要聚合的各个服务的Swagger资源
    @Bean
    public List<SwaggerResource> swaggerResources() {
        List<SwaggerResource> resources = new ArrayList<>();
        // 添加项目A的API文档源
        resources.add(buildSwaggerResource("项目A", "http://localhost:8080/v2/api-docs", "2.0"));
        // 添加项目B的API文档源
        resources.add(buildSwaggerResource("项目B", "http://localhost:8081/v2/api-docs", "2.0"));
        return resources;
    }

    private SwaggerResource buildSwaggerResource(String name, String location, String version) {
        SwaggerResource resource = new SwaggerResource();
        resource.setName(name);
        resource.setLocation(location);
        resource.setSwaggerVersion(version);
        return resource;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("集中式API文档")
                .description("项目A和项目B的统一API文档入口")
                .version("1.0")
                .build();
    }
}

这种方案的好处是独立维护，和业务项目解耦，后续新增服务也只需要在聚合服务里加配置即可。

2. 静态Swagger UI页面聚合

如果不想写后端代码，可以直接用Swagger UI的静态文件快速搭建聚合文档：

下载Swagger UI的静态包（包含html、js、css文件）
修改swagger-initializer.js文件，配置多个API文档的URL列表
将修改后的静态文件部署到Nginx、Apache或者静态文件托管服务上

示例修改后的swagger-initializer.js：

window.onload = function() {
  const ui = SwaggerUIBundle({
    // 配置多个API文档源
    urls: [
      { url: "http://localhost:8080/v2/api-docs", name: "项目A API" },
      { url: "http://localhost:8081/v2/api-docs", name: "项目B API" }
    ],
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })
  window.ui = ui
}

这种方案极其轻量，适合快速搭建临时的集中式文档入口，不需要任何后端开发。