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 14.x
NPM 7.x

Getting Started
- Customization
Installation
Usage
- Command line
- Node module
  - API
  - Validation results
Configuration
- IBM Cloud Validation Ruleset
Warnings Limit
License

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.

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. See the customization documentation for more information.

Installation

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

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

Download an executable binary

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.

Build from source

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.

Build platform-specific binaries

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 packages/validator/bin directory.

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

Usage

Command line

lint-openapi [options] [<files>]

[options]

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

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

debug

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

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

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

IBM Cloud Validation Ruleset

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

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

License

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.

walkerlee/openapi-validator