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
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 describes these rules. 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 two main ways to install the validator, either using NPM or building from source. Installing with NPM is 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 or JavaScript code.
- Clone or download this repository
- Navigate to the root directory of this project.
- Install the dependencies using
npm install - 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 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.
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>]
- -c (--config) <path/to/your/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 (--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.
$ lint-openapi init
- init : The
initcommand initializes a.validatercfile, used to configure the validator. It can also be used to reset the configurable rules to their default values.
$ lint-openapi migrate
- migrate : The
migratecommand migrates a.validatercfile 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 usinglint-openapi init.
None of the above options pertain to these 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 infiles/)
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: string
Default: null
A path to a custom .validaterc file. Note that we are in the process of moving all of our configuration to Spectral. Once the transition is complete, this option will instead provide a path to a custom Spectral config file.
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 are currently transitioning our legacy rules
to the new IBM Cloud Validation ruleset (npm package @ibm-cloud/openapi-ruleset).
Until we finish this transition, we'll have two rulesets - the IBM Cloud Validation ruleset (@ibm-cloud/openapi-ruleset) and the
IBM Cloud Legacy ruleset (included as part of the validator itself).
Once we finish transitioning the legacy rules to the new IBM Cloud Validation ruleset, we will
remove the IBM Cloud Legacy ruleset.
For information on how to configure and use the IBM Cloud Validation Ruleset, click here.
For information on how to configure and use the IBM Cloud Legacy 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
}
| Limit | Default |
|---|---|
| warnings | MAX_VALUE |
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.
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.