This tool is based on the tool and underlying
library.
Please refer to their respective READMEs
here and here for more details on how the merging algorithm works.
The orginal tool has some limitations that this implementation tries to address:
- requires a configuration file on disk.
- paths to input files & output file declared in the configuration file are assumed to be relative to the configuration file path
- the merging algorithm does not resolve
$ref
's to external files. (see also #48)
Specifically for this last limitation, this implementation imports functionality of that bundles all external
$ref
's into the source files before merging the OpenAPI
specifications into a single specifiation. This operation happens in-memory, during file read.
This CLI command accepts options for input directory (-i --inputDir
) and output file (-o --outfile
), and does not require a static configuration file on disk. The tool will recursively search for .yaml
files in the provided input directory (inputDir
).
NOTE: The drawback of this approach is that configurability of the merging algorithm is significantly reduced compared to the original tool.
We process the inputs sequentially such that the first input in the list takes preference and subsequent inputs will be modified to merge seamlessly into the first.
For some parts of the OpenAPI file, like paths
, components
and tags
we attempt to merge the definitions together
such that there are no overlaps and no information is dropped.
However, for other elements of the OpenAPI files, the algorithm simply takes the value that is first defined in the list of OpenAPI files. Examples of elements of the OpenAPI files that follow this pattern are:
- Info
- Servers
- Security Schemes
- ExternalDocumentation
The intention here is that the first file will define these elements and effectively override them from the other files.
During merging, files in inputDir
are sorted alphabetically (desc), so make sure that the file you want to be used as base is named appropriately (eg. _base.yaml
or _main.yaml
)
In order to use this merging cli tool you need to have one or more OpenAPI 3.0 files that you wish to merge.
Run the following command to install the required dependencies and run the CLI command:
yarn && yarn start -i {path-to-spec-files} -o {output-file-path}
Usage: openapi-bundle [options]
Options:
-V, --version output the version number
-i, --inputDir <value> Directory containing OpenAPI specifications
-o, --outFile <value> Output file containing the merged OpenAPI specification
-h, --help display help for command
Both inputDir
and outFile
can be relative or absolute paths, with no correlation between the two.
Vercel's is used to package the CLI tool into an executable, that can be run without Node. Currently, only packaging to
alpine
is implemented. Check out the package:alpine
script in package.json
for more details.