Need help with openapi-validator?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

IBM
204 Stars 40 Forks Other 783 Commits 16 Opened issues

Description

Configurable and extensible validator/linter for OpenAPI documents

Services available

!
?

Need anything else?

Contributors list

Build Status npm-version codecov semantic-release Gitter Commitizen friendly CLA assistant

OpenAPI Validator

This command line tool lets you validate OpenAPI documents according to their specification, either 2.0 or 3.0, as well as IBM-defined best practices.

Prerequisites

  • Node 10.x
  • NPM 5.x

Table of contents

Getting Started

The validator analyzes your API definition and reports any problems within. The validator is highly customizable, and supports both OpenAPI 3.0 and OpenAPI 2.0 (Swagger 2.0) formats. The tool also supports a number of rules from Spectral. You can easily extend the tool with custom rules to meet your specific needs and ensure compliance to your standards.

The default configuration uses both OpenAPI 3.0 rules as well as Spectral rules. The default mode section decscribes these rules. Get started by installing the tool, then run the tool on your API definition.

Customization

You can modify the behavior of the validator for your project to meet your preferred standards. Specific validation "rules" can be turned off, or configured to trigger an error, warning, info, or hint message in the validator output.

Some validations can be configured even further, such as switching the case convention for parameter names. There are also currently some validations that cannot be disabled or configured to a different severity. You can see the rule associated with each message produced by the validator with the

-v
command line option. Rules that are not configurable will show the name
builtin
.

The validator also employs the

Spectral
validation/linting engine to detect certain issues in the API document. Spectral rules can also be configured to trigger an error, warning, info, or hint message in the validator output with the

.spectral.yaml
configuration file. When the validator issues a message as the result of a Spectral rule, the rule name displayed will correspond to the Spectral rule. You must add a Spectral configuration if you want to create a new rule, as opposed to modifying an existing one.

To get started configuring the validator, set up a configuration file. See the Spectral configuration section for more details on customization with Spectral.

Installation

There are two main ways to install the validator, either using NPM or building from source. Installing with NPM is reccomended.

Install with NPM (recommended)

npm install -g ibm-openapi-validator

The

-g
flag installs the tool globally so that the validator can be run from anywhere in the file system. Alternatively, you can pass no flag or the
--save-dev
flag to add the validator as a dependency to your project and run it from your NPM scripts.

Build from source

  1. Clone or download this repository
  2. Navigate to the root directory of this project.
  3. Install the dependencies using
    npm install
  4. Build the command line tool by running
    npm run link
    .

If you installed the validator using

npm install -g ibm-openapi-validator
, you will need to run
npm uninstall -g ibm-openapi-validator
before running
npm run link
.

Platform specific binaries

It is possible to build platform specific binaries for Linux, MacOS, and Windows that do not depend on having node.js installed.

To build these, run

npm run pkg
in the root. The binaries (lint-openapi-linux, lint-openapi-macos, lint-openapi-windows.exe respectively) are built in the 'bin' directory in the root.

Docker container

A community Docker image is publicly available on Docker hub.

docker pull jamescooke/openapi-validator

Once pulled, the container can be run directly, but mount a volume containing the OpenAPI specification file so that it can be accessed.

docker run --volume "$PWD":/data jamescooke/openapi-validator [options] [command] []

Usage

Command line

lint-openapi [options] [command] []
[options]
  • -c (--config) : Path to a validator configuration file. If provided, this is used instead of .validaterc.
  • -d (--default_mode) : This option turns off configuration and runs the validator in default mode.
  • -e (--errors_only) : Only print the errors, ignore the warnings.
  • -j (--json) : Output results as a JSON object
  • -n (--no_colors) : The output is colored by default. If this bothers you, this flag will turn off the coloring.
  • -p (--printvalidatormodules) : Print the name of the validator source file the error/warning was caught it. This can be helpful for developing validations.
  • -v (--verbose) : Increase verbosity of reported results. Use this option to display the rule for each reported result.
  • -r (--ruleset) : Path to Spectral ruleset file, used instead of .spectral.yaml if provided.
  • -s (--report_statistics) : Print a simple report at the end of the output showing the frequency, in percentage, of each error/warning.
  • --debug : Enable debugging output.
  • --version : Print the current semantic version of the validator
  • -h (--help) : This option prints the usage menu.

These options only apply to running the validator on a file, not to any commands.

[command]

$ lint-openapi init
- init : The
init
command initializes a
.validaterc
file, used to configure the validator. It can also be used to reset the configurable rules to their default values.
[command]

$ lint-openapi migrate
- migrate : The
migrate
command migrates a
.validaterc
file from the legacy format to the current format, retaining all custom rules. The new format is required - this command provides an option to keep custom rules without manually updating the file or initializing a new configuration file with all rules set to the defaults using
lint-openapi init
.

None of the above options pertain to these commands.

<files>
  • The OpenAPI document(s) to be validated. All files must be a valid JSON or YAML (only .json, .yml, and .yaml file extensions are supported).
  • Multiple, space-separated files can be passed in and each will be validated. This includes support for globs (e.g.
    lint-openapi files/*
    will run the validator on all files in
    files/
    )

Node module

const validator = require('ibm-openapi-validator');

validator(openApiDoc) .then(validationResults => { console.log(JSON.stringify(validationResults, null, 2)); });

// or, if inside async function const validationResults = await validator(openApiDoc); console.log(JSON.stringify(validationResults, null, 2));

API

validator(openApiDoc, [defaultMode = false])

Returns a

Promise
with the validation results.
openApiDoc

Type:

Object
An object that represents an OpenAPI document.
defaultMode

Type:

boolean
Default:
false
If set to true, the validator will ignore the
.validaterc
file and will use the configuration defaults.

Validation results

The Promise returned from the validator resolves into a JSON object. The structure of the object is:

{
  errors:
  [
    {
      path: 'path.to.error.in.object'
      message: 'Major problem in the OpenAPI document.'
    }
  ],
  warnings:
  [
    {
      path: 'path.to.warning.in.object'
      message: 'Minor problem in the OpenAPI document.'
    }
  ]
}
The object will always have
errors
and
warnings
keys that map to arrays. If an array is empty, that means there were no errors/warnings in the OpenAPI document.

Configuration

Use these sections to customize your traditional and Spectral rules to reflect your API standards.

Setup

To set up the configuration capability, simply run the command

lint-openapi init
. This will create (or overwrite) a
.validaterc
file with all rules set to their default value. This command does not create a
.validateignore
. That file must be created manually. These rules can then be changed to configure the validator. Continue reading for more details.

WARNING: If a

.validaterc
file already exists and has been customized, this command will reset all rules to their default values.

It is recommended to place these files in the root directory of your project. The code will recursively search up the filesystem for these files from wherever the validator is being run. Wherever in the file system the validator is being run, the nearest versions of these files will be used.

Definitions

Specs

The validator supports two API definition specifications - OpenAPI 2.0, aka Swagger 2.0, and OpenAPI 3.0. The validator will automatically determine which spec a document is written in. There are some rules in the validator that only apply to one of the specs and some rules that apply to both. The configuration structure is organized by these "specs". The supported specs are described below:

| Spec | Description | | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | swagger2 | Rules pertaining only to the OpenAPI 2.0 specification. | | oas3 | Rules pertaining only to the OpenAPI 3.0 specification | | shared | Rules pertaining to both of the above specifications. |

Categories

Rules are further organized by categories. Not every category is supported in every spec - these are a superset of the available categories. For the actual structure, see the default values. The supported categories are described below:

| Category | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------- | | operations | Rules pertaining to Operation Objects | | parameters | Rules pertaining to Parameter Objects | | paths | Rules pertaining to Paths Objects | | schemas | Rules pertaining to Schema Objects | | security_definitions | Rules pertaining to Security Definition Objects | | security | Rules pertaining to Security Objects | | walker | Rules pertaining to the entire document. | | pagination | Rules pertaining to pagination |

Rules

Each category contains a group of rules. The spec that each rule applies to is marked in the third column. For the actual configuration structure, see the default values. You can use the

-v
option of the CLI validator to display the rule for each reported result. The supported rules are described below:
operations

| Rule | Description | Spec | | ---------------------------- | ----------------------------------------------------------------------------------- | -------- | | undefinedtag | Flag a tag that is in operations and not listed in

tags
on the top level. | shared | | unusedtag | Flag a tag that is listed in

tags
on the top level that is not used in the spec. | shared | | noconsumesforputorpost | Flag
put
or
post
operations that do not have a
consumes
field. | swagger2 | | get
ophasconsumes | Flag
get
operations that contain a
consumes
field. | swagger2 | | noproduces | Flag operations that do not have a
produces
field (except for
head
and operations that return a 204). | swagger2 | | no
operationid | Flag any operations that do not have an
operationId
field. | shared | | operation
idcaseconvention | Flag any
operationId
that does not follow a given case convention. | shared | | nosummary | Flag any operations that do not have a
summary
field. | shared | | no
arrayresponses | Flag any operations with a top-level array response. | shared | | parameterorder | Flag any operations with optional parameters before a required param. | shared | | operationidnamingconvention | Flag any
operationId
that does not follow naming convention. | shared | | no
requestbodycontent | Flag any operations with a
requestBody
that does not have a
content
field.
| oas3 | | norequestbody_name | Flag any operations with a non-form
requestBody
that does not have a name set with
x-codegen-request-body-name
. | oas3|
pagination

| Rule | Description | Spec | | --------------------------- | ------------------------------------------------------------------------ | ------ | | pagination_style | Flag any parameter or response schema that does not follow pagination requirements. | oas3 |

parameters

| Rule | Description | Spec | | --------------------------- | ------------------------------------------------------------------------ | ------ | | requiredparamhasdefault | Flag any required parameter that specifies a default value. | shared | | noparameterdescription | Flag any parameter that does not contain a

description
field. | shared | | paramnamecaseconvention | Flag any parameter with a

name
field that does not follow a given case convention. | shared | | invalidtypeformatpair | Flag any parameter that does not follow the data type/format rules. | shared | | contenttypeparameter | Flag any parameter that explicitly defines a
Content-Type
. That should be defined by the
consumes
field.
| shared | | accept
typeparameter | Flag any parameter that explicitly defines an
Accept
type. That should be defined by the
produces
field.
| shared | | authorization
parameter | Flag any parameter that explicitly defines an
Authorization
type. That should be defined by the
securityDefinitions
/
security
fields.
| shared | | noinproperty | Flag any parameter that does not define an
in
property. | oas3 | | invalidinproperty | Flag any parameter that has an invalid
in
property. | oas3 | | missingschemaorcontent | Flag any parameter that does not define its data type with
schema
or
content
. | oas3 | | has
schemaandcontent | Flag any parameter that defines data type with both
schema
and
content
. | oas3 |
paths

| Rule | Description | Spec | | --------------------------- | ------------------------------------------------------------------------------------------------------------ | ------ | | missingpathparameter | For a path that contains path parameters, flag any operations that do not correctly define those parameters. | shared | | snakecaseonly | Flag any path segment that does not use snake case. | shared | | pathscaseconvention | Flag any path segment that does not follow a given case convention. snakecaseonly must be 'off' to use. | shared | | duplicatepathparameter | Flag any path parameters that have identical definitions in all operations. | shared |

responses

| Rule | Description | Spec | | ------------------------- | ------------------------------------------------------------ | ---- | | inlineresponseschema | Flag any response object with a schema that doesn't reference a named model. Even if the model is only used once, naming it offers significant benefits for SDK generation. | shared | | noresponsecodes | Flag any response object that has no valid response codes. | oas3 | | nosuccessresponsecodes | Flag any response object that has no success response codes. | oas3 | | noresponsebody | Flag any non-204 success responses without a response body. | oas3 | | ibmstatuscodeguidelines| Flag any violations of status code conventions per IBM API Handbook | oas3 |

schemas

| Rule | Description | Spec | | --------------------------- | ----------------------------------------------------------------------------- | -------- | | invalidtypeformatpair | Flag any schema that does not follow the data type/format rules. | shared | | snakecaseonly | Flag any property with a

name
that is not lower snake case. | shared | | noschemadescription | Flag any schema without a
description
field. | shared | | no
propertydescription | Flag any schema that contains a 'property' without a
description
field. | shared | | description
mentionsjson | Flag any schema with a 'property' description that mentions the word 'JSON'. | shared | | arrayofarrays | Flag any schema with a 'property' of type
array
with items of type
array
. | shared | | inconsistent
propertytype | Flag any properties that have the same name but an inconsistent type. | shared | | propertycaseconvention | Flag any property with a
name
that does not follow a given case convention. snake
caseonly must be 'off' to use. | shared | | propertycasecollision | Flag any property with a
name
that is identical to another property's
name
except for the naming convention | shared | | enum
caseconvention | Flag any enum with a
value
that does not follow a given case convention. snake
caseonly must be 'off' to use. | shared | | jsonorparambinarystring | Flag parameters or application/json request/response bodies with schema type: string, format: binary. | oas3 | | undefinedrequired_properties| Flag any schema with undefined required properties | shared |

security_definitions

| Rule | Description | Spec | | --------------------------- | ------------------------------------------------------------------------------------- | ------ | | unusedsecurityschemes | Flag any security scheme defined in securityDefinitions that is not used in the spec. | shared | | unusedsecurityscopes | Flag any security scope defined in securityDefinitions that is not used in the spec. | shared |

security

| Rule | Description | Spec | | -------------------------------- | ------------------------------------------------------------ | ------ | | invalidnonemptysecurityarray | Flag any non-empty security array this is not of type OAuth2 | shared |

walker

| Rule | Description | Spec | | ----------------------------- | ---------------------------------------------------------------------------- | ------ | | noemptydescriptions | Flag any

description
field in the spec with an empty or whitespace string. | shared | | hascircularreferences | Flag any circular references found in the API document. | shared | | $refsiblings | Flag any properties that are siblings of a
$ref
property. | shared | | duplicate
siblingdescription | Flag descriptions sibling to
$ref
if identical to referenced description. | shared | | incorrect
ref_pattern | Flag internal
$ref
values that do not point to the section they should (e.g. referencing
parameters
from a
schema
field). | shared |

Statuses

Each rule can be assigned a status. The supported statuses are

error
,
warning
,
info
,
hint
and
off
. Some rules can be configured further with configuration options. The format of this configuration is to provide an array, rather than just a string. e.g.
"param_name_case_convention": ["error", "lower_camel_case"]
If just a string is provided for these rule, the default configuration option will be used. If only one value is provided in the array, it MUST be a status. The default configuration option will be used in this case as well. The rules that support configuration options will have two values in the defaults table.

Configuration Options

For rules that accept additional configuration, there will be a limited set of available options.

Case Convention Options
  • Some rules check strings for adherence to a specific case convention. In some cases, the case convention checked is configurable.
  • Rules with configurable case conventions will end in
    _case_convention
    , such as
    param_name_case_convention
    .

| Option | Description | Example | | ---------------- | -------------------------------------------------------- | ----------------- | | lowersnakecase | Words must follow standard lower snake case conventions. | learningoptout | | uppersnakecase | Words must follow standard upper snake case conventions. | LEARNINGOPTOUT | | uppercamelcase | Words must follow standard upper camel case conventions. | LearningOptOut | | lowercamelcase | Words must follow standard lower camel case conventions. | learningOptOut | | k8scamelcase | Words must follow Kubernetes API camel case conventions. | learningOptOutAPI | | lowerdashcase | Words must follow standard lower dash case conventions. | learning-opt-out | | upperdashcase | Words must follow standard upper dash case conventions. | LEARNING-OPT-OUT |

Configuration file

Non-Spectral configurations are defined in a file, titled .validaterc. Spectral rules must be configured in

.spectral.yaml
rather than in
.validaterc
.
Additionally, certain files can be ignored by the validator. Any glob placed in a file called

.validateignore
will always be ignored by the validator at runtime. This is set up like a
.gitignore
or a
.eslintignore
file.

The configuration file must be structured as a JSON object with specs as first-level keys, categories as second-level keys, rules as third-level keys, and statuses as values for the 'rules' objects.

If a rule is not included in the file, that rule will be set to the default status automatically. See the Default Values for more info.

For an example of the structure, see the defaults file.

The easiest way to create a

.validaterc
file is using the initialization command.

Default mode

The validator has a set of predefined default statuses for each rule that are used in 'default mode'.

Default mode can be turned on with the command line option

-d
. If this option is given, the
.validaterc
file will be ignored.

If a

.validaterc
file does not exist at the root directory of your project, the validator will automatically run in default mode.

The default values for each rule are described below.

Default values

swagger2
operations

| Rule | Default | | --------------------------- | ------- | | noconsumesforputorpost | error | | getophasconsumes | warning | | no_produces | error |

oas3
operations

| Rule | Default | | --------------------------- | ------- | | norequestbodycontent | error | | norequestbodyname | warning |

parameters

| Rule | Default | | --------------------------- | ------- | | noinproperty | error | | invalidinproperty | error | | missingschemaorcontent | error | | hasschemaandcontent | error |

responses

| Rule | Default | | ------------------------- | ------- | | noresponsecodes | error | | nosuccessresponsecodes | warning | | noresponsebody | warning | | ibmstatuscodeguidelines| warning |

schemas

| Rule | Default | | --------------------------- | ------- | | jsonorparambinarystring | warning | | undefinedrequiredproperties | warning |

shared
operations

| Rule | Default | | ---------------------------- | ------- | | undefinedtag | warning | | unusedtag | warning | | nooperationid | warning | | operationidcaseconvention | warning, lowersnakecase | | nosummary | warning | | noarrayresponses | error | | parameterorder | warning | | operationidnamingconvention | warning |

pagination

| Rule | Default | | --------------------------- | --------| | pagination_style | warning |

parameters

| Rule | Default | | --------------------------- | --------| | noparameterdescription | error | | paramnamecaseconvention | error, lowersnakecase | | invalidtypeformatpair | error | | contenttypeparameter | error | | accepttypeparameter | error | | authorizationparameter | warning | | requiredparamhasdefault | warning |

paths

| Rule | Default | | --------------------------- | ------- | | missingpathparameter | error | | snakecaseonly | off | | pathscaseconvention | error, lowersnakecase |

responses

| Rule | Default | | ------------------------- | ------- | | inlineresponseschema | warning |

security_definitions

| Rule | Default | | --------------------------- | ------- | | unusedsecurityschemes | warning | | unusedsecurityscopes | warning |

security

| Rule | Default | | -------------------------------- | ------- | | invalidnonemptysecurityarray | error |

schemas

| Rule | Default | | --------------------------- | ------- | | invalidtypeformatpair | error | | snakecaseonly | off | | noschemadescription | warning | | nopropertydescription | warning | | descriptionmentionsjson | warning | | arrayofarrays | warning | | inconsistentpropertytype | warning, [code, default, type, value]]
(list of property names to exclude) | | property
caseconvention | error, lowersnakecase | | propertycasecollision | error | | enumcaseconvention | warning, lowersnake_case |

walker

| Rule | Default | | ----------------------------- | ------- | | noemptydescriptions | error | | hascircularreferences | warning | | $refsiblings | off | | duplicatesiblingdescription | warning | | incorrectref_pattern | warning |

Spectral configuration

Currently the validator configures Spectral to check the following rules from its “oas" ruleset:

no-eval-in-markdown: true
no-script-tags-in-markdown: true
openapi-tags: true
operation-description: true
operation-operationId-unique: true
operation-parameters: true
operation-tags: true
operation-tag-defined: true
path-keys-no-trailing-slash: true
path-not-include-query: true
typed-enum: true
oas2-api-host: true
oas2-api-schemes: true
oas2-host-trailing-slash: true
oas2-valid-example: true
oas2-valid-definition-example: true
oas2-anyOf: true
oas2-oneOf: true
oas2-operation-formData-consume-check: true
oas3-api-servers: true
oas3-examples-value-or-externalValue: true
oas3-server-trailing-slash: true
oas3-valid-example: true
oas3-valid-schema-example: true

This ruleset has the alias

ibm:oas
, and you can "extend" this ruleset or specify your own custom ruleset with a Spectral ruleset file. Note that all of the rules in the
spectral:oas
ruleset are defined in
ibm:oas
but only the rules listed above are enabled by default.

The

ibm:oas
ruleset also includes custom Spectral rules, documented here. These are configurable rules in the
ibm:oas
ruleset that are not part of the
spectral:oas
ruleset.

You can provide a Spectral ruleset file to the IBM OpenAPI validator in a file named

.spectral.yaml
in the current directory or with the
--ruleset
command line option of the validator.

Changing Spectral rule severity

Any rule in the

ibm:oas
ruleset can be configured to trigger an error, warning, info, or hint message in the validator output. For example, to configure the
openapi-tags
rule to trigger an
info
message instead of a
warning
, specify the following in your Spectral ruleset file:
extends: ibm:oas
rules:
  openapi-tags: warn

To completely disable a rule, use the severity of

off
. For example, to disable the
operation-tags
rule, specify the following in your Spectral ruleset file:
extends: ibm:oas
rules:
  operation-tags: off

Since the

ibm:oas
ruleset includes all the rules in
spectral:oas
, you can also enable rules from that ruleset that are disabled by default in
ibm:oas
. For example, to enable the
info-contact
rule with it's default severity (
warning
), specify the following in your Spectral ruleset file:
extends: ibm:oas
rules:
  info-contact: true

You could also set the severity of

info-contact
explicitly to
error
,
warn
,
info
, or
hint
.

Custom Spectral rules

New custom rules can be specified using a simple but powerful yaml syntax or with custom Javascript functions. Use the documentation on Spectral custom rules in order to add these to your .spectral.yaml file.

Warnings Limit

You may impose a warning limit on your API definitions. If the number of warnings issued exceeds the warning limit, the exit code will be set to 1. If the Validator is part of your CI build, this will cause the build to fail.

To impose a warnings limit on a project, add a

.thresholdrc
to your project. It is recommended to add this file to the root of the project. The validator recursively searches up the filesystem from whichever directory the validator is invoked, and the nearest
.thresholdrc
will be used.

The format for the

.thresholdrc
file is a top-level JSON object with a
"warnings"
field (shown below).
{
  "warnings": 0
}
limits

| Limit | Default | | ----------------------- | --------- | | warnings | MAX_VALUE |

Turning off
update-notifier

This package uses

update-notifier
to alert users when new versions of the tool are available. To turn this feature off, follow these instructions from the package authors. It is recommended to keep this feature on to help stay up to date with the latest changes.

License

Copyright 2017 SmartBear Software

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 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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.