Merges multiple OpenAPI document files into a single file.
MIT License
Yet another CLI tool for merging multiple OpenAPI files into a single file.
$include
keyword: same as $ref
, except it merges the object with sibling elements. ($ref
ignores them)$ npm install -g openapi-merger
$ openapi-merger -i openapi.yaml -o merged.yaml
openapi-merger introduces the special keyword $include
.
It has similar syntax as $ref
, which takes JSON reference as its value.
$include: 'reference to content'
The biggest difference is that $include
replaces itself directly by the referenced content, allowing to merge its sibling elements.
If $include
is used in an object and then referenced content is an object too, they are merged.
object:
$include: object.yml
key3: val3
key1: val1
key2: val2
object:
key1: val1
key2: val2
key3: val3
Arrays go in the same manner.
array:
- $include: array.yml
- val3
- val1
- val2
array:
- val1
- val2
- val3
If you want not to merge arrays, use $include
in a nested array.
array:
- - $include: array.yml
- val3
- val1
- val2
array:
- - val1
- val2
- val3
$include
can be used multiple times in the same place by appending #
with some ID, avoiding key duplication.
$include#foo: ./foo.yml
$include#bar: ./bar.yml
$include
is capable of modification and filtering of the keys of the referenced content.
This is useful when you want to aggregate multiple OpenAPI documents of backend services into one for API Gateway.
To utilize this function, a configuration file should be given by -c
option.
The configuration file is like following:
include:
# 'foo' class, which add '/v1' prefix to each key
foo:
prefix: /v1
# 'bar' class, which selects only keys matching to regex
# here excluding paths that begins 'internal'
bar:
filter: ^(?!/internal).*
Use defined class as following:
# using foo class
$include.foo: paths.yml
# using bar class
$include.bar: paths.yml
/users:
post:
...
/users/{id}:
get:
...
/internal/pets:
post:
...
# from $include.foo
/v1/users:
post:
...
/v1/users/{id}:
get:
...
/v1/internal/pets:
post:
...
# from $include.bar
/users:
post:
...
/users/{id}:
get:
...
You can still use #
notation to avoid key conflicts like below.
$include#a.foo: paths1.yml
$include#b.foo: paths2.yml