An authoring tool for OpenAPI specifications
APACHE-2.0 License
openapi-preprocessor
is an processing tool that gives flexibility to API documentation authors for writing OpenAPI 2.0/3.x specifications.
$inline
, $merge
) to remove duplication (source of inconsistencies).$inline
, $merge
) to produce complex schemas that share subset of properties.$inline
, $merge
) that allow to avoid duplication of content and ease the writing of consistent documentation/components/schemas
), parameters (under /components/parameters
) and responses (under /components/responses
). This reduces risk of leaking work in progress or internal details.A Go development environment is required. Go 1.12+ recommended.
Build openapi-preprocessor
binary and install in $GOPATH/bin
:
$ make install
openapi-preprocessor [<option>...] <file>
$ref
{ "$ref": "<file>" }
{ "$ref": "<file>#<pointer>" }
{ "$ref": "#<pointer>" }
$ref
is like in OpenAPI, but it can reference content in external files using relative URLs as well as intra-document. The referenced part of the pointed document is injected into the output document.
Restrictions:
{"$ref": "external.yml#/components/parameters/Id"}
will import the content to /components/parameters/Id
. This implies that partial files should have the same layout as a full spec (this is a feature as it enforces readability of partials).$ref
are not allowed as the semantics in JSON Schema and Swagger/OpenAPI has evolved and the support in consuming tools may vary. Use $merge
instead that has a strict behaviour in this tool.$inline
{ "$inline": "<file>#<pointer>"}
{
"$inline": "<file>#<pointer>",
"pointer1": <value>, // Overrides value at <file>#<pointer>/pointer1
"pointer2/slash": <value> // Overrides value deeply at <file>#<pointer>/pointer/slash
}
$inline
is an OpenAPI extension allowing to inject a copy of another part of a document in place. Keys along the $inline
keyword are JSON pointers (with the leading /
removed) allowing to override some parts of the inlined content.
If the target of $inline
is a $ref
and $inline
has overrides, the link is dereferenced recursively before inlining.
Note: deep inlining (inlining a node which itself use $inline
in its tree) might work, but will probably not (see issue #6 as an example). Use instead $merge
which supports it.
$merge
{
"$merge": "<file>#<pointer>",
"key": <value>,
"key/slash": <value> // Overrides value at <file>#<pointer>/key~1slash
}
{
"$merge": [
"<file1>#<pointer1>",
"<file2>#<pointer2>" // Overrides keys from <file1>#<pointer1>
]
"key": <value>,
"key/slash": <value> // Overrides value at <file2>#<pointer2>/key~1slash
}
$merge
is an OpenAPI extension allowing to copy a node, overriding some keys. This is a kind of inlined $ref
with keys overrides.
See the testsuite.
Running a basic example:
$ make
$ ./openapi-preprocessor testdata/10-ref-ext/input.yml
Copyright 2018-2022 Olivier Mengué
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.