参考文献：
https://davidgarcia.dev/posts/how-to-split-open-api-spec-into-multiple-files/
https://github.com/kpramesh2212/openapi-merger-plugin
https://swagger.io/specification/
https://github.com/OAI/OpenAPI-Specification

文章项目源码

放上源码主要是为了提供技术上的解决方案，对于博客中关于技术背后的思考，请用批判的眼光看待。

https://download.csdn.net/download/weixin_44268792/50599037

文章结构

1. 解决方案；
2. 背景介绍；
3. 不同方案的优缺点；
4. 总结。

合并方案

方案一、swagger-cli

一个主openapi文件引用（reference）一个或者多个其他的文件，生成一个完整的文件。

测试准备

1. param.yaml

   get:
     summary: 获取Meaning列表
     operationId: listMeaning
     tags:
       - meaning
   

2. openapi.yaml

   openapi: 3.0.3
   info:
       title: DESIGN服务
       version: 0.0.1
   servers:
       - url: 'http://127.0.0.1:8082/design'
   paths:
       /meaning:
           $ref: './param.yaml'
   

依赖安装

1. 安装Node.js；
2. 安装swagger-cli，npm install -g swagger-cli ；（安装失败，尝试使用管理员权限重试。）
3. build

   # swagger-cli bundle 输入 --outfile 输出 --type 格式
   swagger-cli bundle openapi.yaml --outfile _build/openapi.yaml --type yaml
   

4. 如果成功，会生成一个_build目录（IDEA尝试刷新目录），里面有一个openapi.yaml文件，内容如下。

   openapi: 3.0.3
   info:
     title: DESIGN服务
     version: 0.0.1
   servers:
     - url: 'http://127.0.0.1:8082/design'
   paths:
     /meaning:
       get:
         summary: 获取Meaning列表
         operationId: listMeaning
         tags:
           - meaning
   

方案二、openapi-merger-plugin

多个相互独立的openapi文件，以OpenAPI规范为合并策略，组合成一个大的openapi文件。

测试准备

因为yaml内容比较占用篇幅，测试文件自行下载源码提取：

依赖安装

1. pom配置

<build>
    <plugins>
        <plugin>
            <groupId>com.rameshkp</groupId>
            <artifactId>openapi-merger-maven-plugin</artifactId>
            <version>1.0.4</version>
            <configuration>
            	<!--输入目录-->
                <inputDir>${project.basedir}/src/main/resources/compose</inputDir>
                <!--输出目录-->
                <outputDir>${project.basedir}/src/main/resources/compose</outputDir>
                <!--输出类型YAML/JSON-->
                <outputFileFormat>YAML</outputFileFormat>
                <!--文件名称-->
                <outputFileName>open</outputFileName>
                <openApi>
                	<!-- openapi的版本 -->
                    <version>3.0.1</version>
                    <info>
                    	<!--你的maven项目的版本-->
                        <version>${app.version}</version>
                    </info>
                </openApi>
            </configuration>
        </plugin>
    </plugins>
</build>

2. build
   mvn openapi-merger:merge
3. 成功会生成相应的文件

将如何使用放在最前面是因为考虑到了一些实际情况，平时自己在网络上搜索一些答案时，明明几行代码能解决的事，却要看完别人的整篇文档，心态很炸裂。
于是决定把结果写在前面，背景原因写在后面。

对OpenApi文件进行合并的背后原因：有分才有合

往往一个业务系统会向外部暴露许多的接口，当团队选择使用OpenApi来维护这些接口的时候，就会出现一个问题——所有接口元信息都在一个openapi文件中。

接口元信息数量太多，维护苦难、新增或修改不方便、查找不方便。有时候想看一看一个接口的信息，于是就在一个几千行的文件里跳来跳去，不时还会卡顿上一两秒。

为了更方便管理接口元信息，我们很容易就想到了一个解决方案——拆分。

在软件工程中，因为数量持续递增，而导致系统可维护性降低的例子屡见不鲜，而拆分之后分类管理就很简单的解决了这类问题。

往往解决一个现有问题之后，会随之带来多个新的的问题。

在项目中使用openapi可能是需要使用openapi文件来生成api的接口文档、或者方便引入到一些其他系统使用、或者使用了swagger-codegen插件等原因。在openapi文件被拆分之后，项目中的组件变得不支持了。于是新的问题是，openapi拆分之后如何能继续被各个依赖的组件所支持。

显然，最容易的方法不是去修改各个组件🐶，而是在程序运行的时候通过某种方式将拆分的文件合并起来，让程序不报错。

合并方式

拆分openapi文件的常用方法有两种：

• 组合（compose）
  将多个相互独立的yaml/json文件，根据OpenAPI-Specification，合并成一个新的文件。

• 引用（reference）
  主文件通过reference的方式引用子文件，最终生成一个完整的新文件。

两种合并方式对应的是不同的拆分方式，都有各自的优缺点，根据系统需求的不同可以选用不同的方式。

compose

将一个大的openapi文件拆分成多个独立的文件，文件与文件之间没有之间的关联。
优点：

• 耦合度低，因为每一个文件都是单独可用的，文件与文件之间不存在引用关系；
• 扩展性强，如果想合并其他系统的openapi文件，不需要做任何配置。

缺点：

• 使用的开源插件对复杂的openapi文件合并的支持并不好；
• 如果某个文件丢失，合并过程无法及时发现。

reference

用一个根的openapi文件引用多个局部的文件，文件与文件之间存在间接或者直接的依赖关系。

优点：

• swagger-cli是一个比较成熟的技术，可以应对复杂文件的合并；
• 能够在合并过程中及时发现文件格式和引用的错误。

缺点：

• 耦合度高，在文件中查找内容会从最初的在一个文件中跳跃，变成在多个文件中跳跃；
• swagger-cli依赖npm，这使项目引入了无关技术。

总结

两种方案的合并原则都是技术openapi规范的，如果开源组件的无法满足业务需求，也可以通过openapi规范自己实现一套合并方案。