Noiseless Party Machine

    openapi-examples-validator

    4.7.1 • Public • Published

    openapi-examples-validator

    Validates embedded JSON-examples in OpenAPI-specs (v2 and v3 are supported)

    npm version Standard Version Run tests Coverage Status Mutation testing badge Maintainability Known Vulnerabilities Docker Hub

    Prerequisites

    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
      -r, --all-properties-required              make all the properties in the schema required
      -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",
      "$.paths./.post.parameters[?(@.in==="body")].schema": "test/data/v2/post-request/*.json"
    }

    It is possible to use wildcards in the command line to select multiple mapping files, and it is possible to use wildcards inside the mapping file to select multiple examples.

    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 and double are supported for the type number. The format int64 is only available for the type string, though (due to the precision-limitations of Javascript).
    • The options --no-additional-properties and --all-properties-required are not compatible with sub-schemas combiner keyword. A warning will be logged if one model is skipped because it contains a combiner keyword.

    Test

    To run the tests, execute

    npm test
    

    or to check the coverage

    npm run coverage
    

    Install

    npm i openapi-examples-validator

    DownloadsWeekly Downloads

    7,916

    Version

    4.7.1

    License

    MIT

    Unpacked Size

    644 kB

    Total Files

    135

    Last publish

    Collaborators

    • codekie