多应用环境下OpenAPI规范文件集中管理方案咨询

针对多应用分散维护OpenAPI规范、变更同步成本高的问题，以下是几种替代单体仓库的可行方案，均能适配现有Maven+openapi-generator-maven-plugin的构建流程：

方案1：将OpenAPI规范打包为Maven Artifact #

把每个应用的OpenAPI规范（yaml/json文件）打包成独立的Maven构件，上传到公司内部的Maven仓库（如Nexus、Artifactory），其他应用通过依赖引入的方式获取规范文件。

操作步骤： #

1. 规范发布方：在自身项目中配置Maven插件，将规范文件打包为带classifier的构件：

   <build>
       <plugins>
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-assembly-plugin</artifactId>
               <executions>
                   <execution>
                       <id>package-openapi-spec</id>
                       <phase>package</phase>
                       <goals>
                           <goal>single</goal>
                       </goals>
                       <configuration>
                           <classifier>openapi</classifier>
                           <appendAssemblyId>false</appendAssemblyId>
                           <fileSets>
                               <fileSet>
                                   <directory>${project.basedir}/src/main/openapi</directory>
                                   <outputDirectory>/</outputDirectory>
                                   <includes>
                                       <include>*.yaml</include>
                                   </includes>
                               </fileSet>
                           </fileSets>
                       </configuration>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>
   

   执行mvn deploy将构件上传到Maven仓库。

2. 规范依赖方：

   • 引入规范构件作为依赖：

     <dependencies>
         <dependency>
             <groupId>com.yourcompany</groupId>
             <artifactId>service-a-openapi</artifactId>
             <version>1.0.0</version>
             <classifier>openapi</classifier>
             <type>jar</type>
         </dependency>
     </dependencies>
     

   • 使用maven-dependency-plugin将规范文件从依赖中提取到本地构建目录：

     <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-dependency-plugin</artifactId>
         <executions>
             <execution>
                 <id>extract-openapi-spec</id>
                 <phase>generate-sources</phase>
                 <goals>
                     <goal>unpack</goal>
                 </goals>
                 <configuration>
                     <artifactItems>
                         <artifactItem>
                             <groupId>com.yourcompany</groupId>
                             <artifactId>service-a-openapi</artifactId>
                             <version>1.0.0</version>
                             <classifier>openapi</classifier>
                             <outputDirectory>${project.build.directory}/openapi-specs</outputDirectory>
                             <includes>*.yaml</includes>
                         </artifactItem>
                     </artifactItems>
                 </configuration>
             </execution>
         </executions>
     </plugin>
     

   • 在openapi-generator插件中引用提取后的规范文件：

     <plugin>
         <groupId>org.openapitools</groupId>
         <artifactId>openapi-generator-maven-plugin</artifactId>
         <executions>
             <execution>
                 <id>generate-service-a-client</id>
                 <phase>generate-sources</phase>
                 <goals>
                     <goal>generate</goal>
                 </goals>
                 <configuration>
                     <inputSpec>${project.build.directory}/openapi-specs/service-a.yaml</inputSpec>
                     <!-- 其他生成配置（如客户端类型、包名等） -->
                 </configuration>
             </execution>
         </executions>
     </plugin>
     

优势： #

• 复用现有Maven仓库的版本管理、权限控制体系，无需额外搭建服务；
• 规范版本变更时，仅需更新依赖版本号，构建自动拉取最新文件，避免手动同步。

方案2：搭建内部OpenAPI注册中心 #

部署专门的OpenAPI注册服务，统一存储所有应用的规范文件并提供版本化查询接口，应用构建时通过API拉取指定版本的规范。

操作步骤： #

1. 部署注册中心：基于Spring Boot自定义简单服务，或使用开源工具（如Spring Cloud Contract Registry），实现规范的上传、版本管理、查询功能。
2. 规范发布方：在CI/CD流程中添加步骤，将自身规范文件上传到注册中心（如用curl调用API）。
3. 规范依赖方：在Maven构建中使用exec-maven-plugin拉取规范：

   <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>exec-maven-plugin</artifactId>
       <executions>
           <execution>
               <id>fetch-service-b-spec</id>
               <phase>generate-sources</phase>
               <goals>
                   <goal>exec</goal>
               </goals>
               <configuration>
                   <executable>curl</executable>
                   <arguments>
                       <argument>-H</argument>
                       <argument>"Authorization: Bearer ${registry.token}"</argument>
                       <argument>-o</argument>
                       <argument>${project.build.directory}/openapi-specs/service-b.yaml</argument>
                       <argument>http://your-registry:8080/api/specs/service-b/1.0.1</argument>
                   </arguments>
               </configuration>
           </execution>
       </executions>
   </plugin>
   

   后续直接用拉取的文件调用openapi-generator插件即可。

优势： #

• 支持规范的可视化查看、格式校验、变更对比，适合大规模微服务场景；
• 可集成CI/CD流程，实现规范变更的自动校验与通知。

方案3：使用Git子模块引入规范目录 #

将每个应用的OpenAPI规范放在自身仓库的固定目录（如src/main/openapi），依赖方通过Git子模块仅引入该规范目录，而非整个应用仓库。

操作步骤： #

1. 添加子模块：在依赖方项目中执行Git命令，引入目标应用的规范目录：

   git submodule add --depth 1 --filter=blob:none https://git.yourcompany.com/service-c.git src/main/submodules/service-c
   

   --depth 1和--filter=blob:none用于减少拉取体积，仅获取最新版本的规范目录。
2. Maven配置：直接引用子模块中的规范文件路径：

   <plugin>
       <groupId>org.openapitools</groupId>
       <artifactId>openapi-generator-maven-plugin</artifactId>
       <configuration>
           <inputSpec>${project.basedir}/src/main/submodules/service-c/src/main/openapi/service-c.yaml</inputSpec>
           <!-- 其他生成配置 -->
       </configuration>
   </plugin>
   

3. 更新规范：当目标应用的规范变更后，依赖方执行git submodule update --remote拉取最新版本。

优势： #

• 规范与应用代码同仓管理，变更可联动提交，便于追溯；
• 无需额外服务，依赖Git生态即可实现版本控制。

方案4：基于共享存储服务托管规范 #

利用内部共享存储（如NFS、MinIO、阿里云OSS等）按应用+版本的目录结构存储规范文件，依赖方在构建时从存储服务下载指定版本的文件。

操作步骤： #

1. 存储结构规划：比如在MinIO中创建openapi桶，目录结构为/[服务名]/[版本号]/[规范文件名].yaml。
2. 规范发布方：在CI/CD流程中添加上传步骤，将规范文件推送到共享存储的对应目录。
3. 规范依赖方：使用wagon-maven-plugin从存储服务下载规范：

   <plugin>
       <groupId>org.codehaus.mojo</groupId>
       <artifactId>wagon-maven-plugin</artifactId>
       <executions>
           <execution>
               <id>download-service-d-spec</id>
               <phase>generate-sources</phase>
               <goals>
                   <goal>download-single</goal>
               </goals>
               <configuration>
                   <url>s3://your-minio-bucket/openapi/service-d/1.0.0/</url>
                   <fromFile>service-d.yaml</fromFile>
                   <toFile>${project.build.directory}/openapi-specs/service-d.yaml</toFile>
                   <serverId>minio-server</serverId>
               </configuration>
           </execution>
       </executions>
   </plugin>
   

   其中serverId对应的账号密码配置在settings.xml中。

优势： #

• 存储成本低，适合大量静态规范文件的归档与管理；
• 支持权限控制，可灵活配置不同应用的访问权限。

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