README
openapi-examples-validator
Validates embedded JSON-examples in OpenAPI-specs (v2 and v3 are supported)
Prerequisites
- Node.js >=10.
Install
Install using npm:
npm install -g openapi-examples-validator
Usage
openapi-examples-validator [options] <filepath>
Validate embedded examples in OpenAPI-specs (JSON and YAML supported).
To validate external examples, use the `-s` and `-e` option.
To pass a mapping-file, to validate multiple external examples, use the `-m` option.
Options:
-V, --version output the version number
-s, --schema-jsonpath <schema-jsonpath> Path to OpenAPI-schema, to validate the example file against
-e, --example-filepath <example-filepath> file path to example file, to be validated
-m, --mapping-filepath <mapping-filepath> file path to map, containing schema-paths as key and the file-path(s) to
examples as value. If wildcards are used, the parameter has to be put in
quotes.
-c, --cwd-to-mapping-file changes to the directory of the mapping-file, before resolving the
example's paths. Use this option, if your mapping-files use relative paths
for the examples
-n, --no-additional-properties don't allow properties that are not described in the schema
-h, --help output usage information
The validator will search the OpenAPI-spec for response-examples and validate them against its schema.
If an external example has to be verified, the -s
and -e
option has to be used.
For example:
$ openapi-examples-validator -s $.paths./.get.responses.200.schema -e example.json openapi-spec.json
To validate multiple external examples, pass a mapping file with a similar structure along with the -m
option:
{
"$.paths./.get.responses.200.schema": [
"test/data/external-examples-valid-example1.json",
"test/data/external-examples-valid-example2.json",
"test/data/external-examples-invalid-type.json"
],
"$.paths./.get.responses.300.schema": "test/data/external-examples-invalid-missing-link.json"
}
Errors will be written to stderr
.
Sample output of validation errors:
[
{
"keyword": "type",
"dataPath": ".versions[0].id",
"schemaPath": "#/properties/versions/items/properties/id/type",
"params": {
"type": "string"
},
"message": "should be string",
"examplePath": "/~1/get/responses/200/examples/application~1json"
}
]
Docker
Example usage:
$ docker run --rm -i \
--user=$(id -u) \
-v ${PWD}:/data \
codekie/openapi-examples-validator:latest \
/data/test/data/v3/simple-api-with-examples-with-refs-invalid.yml
Caveat
- The formats
int32
,float
anddouble
are supported for the typenumber
. The formatint64
is only available for the typestring
, though (due to the precision-limitations of Javascript). - The option
--no-additional-properties
does not work, ifallOf
is used to combine subschemas.- Enabling this flag will not apply
additionalProperties
to any subschemas that use these combiner keywords. - A warning will be logged if setting the
additionalProperties
flag has been skipped.
- Enabling this flag will not apply
Test
To run the tests, execute
npm test
or to check the coverage
npm run coverage