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.

• Node 12.x
• NPM 7.x

• Getting Started
  • Customization
• Installation
  • Install with NPM (recommended)
  • Build from source
  • Platform specific binaries
  • Docker container
• Usage
  • Command line
  • Node module
    • API
    • Validation results
• Configuration
  • IBM Cloud Validation Ruleset
• Warnings Limit
• License

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.

Get started by installing the tool, then run the tool on your API definition.

You can modify the behavior of the validator for your project to meet your preferred standards. See the customization documentation for more information.

There are three ways to install the validator: using NPM, downloading a platform-specific binary, or building from source.

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 or JavaScript code.

Platform-specific binary files are packaged with each release for MacOS, Linux, and Windows. See the releases page to download the executable for your platform. These do not depend on Node.JS being installed.

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.

It is also possible to build platform specific binaries from the source code by running npm run pkg in the project root directory. The binaries (lint-openapi-macos, lint-openapi-linux, lint-openapi-windows.exe) will be in the project's bin directory.

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] [<files>]

lint-openapi [options] [command] [<files>]

• -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 (--print_validator_modules) : 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/your/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.

• 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/)

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));

Returns a Promise with the validation results.

Type: Object An object that represents an OpenAPI document.

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

Type: boolean Default: false If set to true, the validator will log additional debug information during execution.

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.

Within the openapi-validator project, we have transitioned our legacy rules to the new IBM Cloud Validation Ruleset (npm package @ibm-cloud/openapi-ruleset).

For information on how to configure and use the IBM Cloud Validation Ruleset, click here.

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
}

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.