OpenAPI Validator

The IBM OpenAPI Validator lets you validate OpenAPI 3.0.x and OpenAPI 3.1.x documents for compliance with the OpenAPI specifications, as well as IBM-defined best practices.

Prerequisites

• Node 16.0.0+
• NPM 8.3.0+

Table of contents

• Getting Started
  • Ruleset
  • Customization
• Installation
  • Install with NPM (recommended)
  • Download an executable binary
  • Build from source
    • Build platform-specific binaries
  • Container image
    • Building your own
• Usage
  • Command Syntax
  • Configuration
    • Configuration Properties
      • colorizeOutput
      • errorsOnly
      • files
      • ignoreFiles
      • limits
      • logLevels
      • outputFormat
      • ruleset
      • summaryOnly
• Validator Output
  • Text
  • JSON
• Logging
• Contributing
• License

Getting Started

The validator analyzes your API definition and reports any problems within. The validator is highly customizable, and supports OpenAPI 3.0.x and 3.1.x documents. 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.

Ruleset

By default, the validator will use the IBM Cloud Validation Ruleset (npm package @ibm-cloud/openapi-ruleset). However, if the validator detects the presence of any of the standard Spectral ruleset files (spectral.yaml, spectral.yml, spectral.json, or spectral.js) in the current directory (from which the validator is being run) or in any containing directory within the file system, then that ruleset file will be used instead. To explicitly specify an alternate ruleset, you can use the -r/--ruleset option (or the ruleset configuration property) to specify the name of your custom ruleset file.

If one of the standard Spectral ruleset files are present and you'd like to force the use of the IBM Cloud Validation Ruleset instead, you can use -r default or --ruleset default (or set the ruleset configuration property to the value 'default').

Details about these options are provided below in the Usage section.

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

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.

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.

Container image

Run the validator with the container image by mounting your API definition.

If it is named openapi.yaml in the current directory, then run:

docker run \
  --rm --tty \
  --volume "$PWD:/data:ro" \
  ibmdevxsdk/openapi-validator:latest \
    openapi.yaml

You should replace latest with a specific tagged version to avoid any surprises when new releases are published.

Flag and argument syntax is the same as described in Usage, but file paths are relative to /data.

To use a custom ruleset named ruleset.yaml in the current directory, run:

docker run \
  --rm --tty \
  --volume "$PWD:/data:ro" \
  ibmdevxsdk/openapi-validator:latest \
    --ruleset ruleset.yaml \
    openapi.yaml

Building your own

If the existing image doesn't suit your needs, you could extend it and build your own.

For example, to build a validator image with your own custom ruleset package installed, make a Dockerfile like this:

FROM ibmdevxsdk/openapi-validator:latest
RUN npm install -g ${your-ruleset-pkg-here}

Usage

Command Syntax

Usage: lint-openapi [options] [file...]

Run the validator on one or more OpenAPI 3.x documents

Options:
  -c, --config <file>            use configuration stored in <file> (*.json, *.yaml, *.js)
  -e, --errors-only              include only errors in the output and skip warnings (default is false)
  -i, --ignore <file>            avoid validating <file> (e.g. -i /dir1/ignore-file1.json --ignore /dir2/ignore-file2.yaml ...) (default is []) (default: [])
  -j, --json                     produce JSON output (default is text)
  -l, --log-level <loglevel>     set the log level for one or more loggers (e.g. -l root=info -l ibm-schema-description-exists=debug ...)  (default: [])
  -n, --no-colors                disable colorizing of the output (default is false)
  -r, --ruleset <file>           use Spectral ruleset contained in `<file>` ("default" forces use of default IBM Cloud Validation Ruleset)
  -s, --summary-only             include only the summary information and skip individual errors and warnings (default is false)
  -w, --warnings-limit <number>  set warnings limit to <number> (default is -1)
  --version                      output the version number
  -h, --help                     display help for command

where [file...] is a space-separated list containing the filenames of one or more OpenAPI 3.x documents to be validated. The validator supports OpenAPI documents in either JSON or YAML format, using these supported file extensions:

.json
.yaml
.yml

Assuming your command shell supports the use of wildcards, you can use wildcards when specifying the names of files to be validated. For example, to run the validator on all .yaml files contained in the /my/apis directory, you could use this command:

lint-openapi /my/apis/*.yaml

Note that the -i/--ignore option can be particularly useful when using wildcards because it allows you to skip the validation of specific files which might otherwise be included in a validation run. For example, to validate all .yaml files in the /my/apis directory, except for /my/apis/broken-api.yaml use the command:

lint-openapi /my/apis/*.yaml -i /my/apis/broken-api.yaml

Configuration

In addition to command-line options, the validator supports the use of a configuration file containing options as well. A configuration file can be in JSON, YAML or Javascript format, using these supported extensions: .json, .yaml, .yml, and .js. Its structure must comply with this JSON schema.

You can specify the name of your configuration file with the -c/--config option. Here's an example:

lint-openapi -c my-config.yaml my-api.json

where my-config.yaml might contain the following:

errorsOnly: true
limits:
  warnings: 25
outputFormat: 'json'
summaryOnly: true

This would be equivalent to this command:

lint-openapi --errors-only --warnings-limit=25 --json --summary-only my-api.json

When using both a configuration file and various command-line options, be aware that the options specified via the command-line will take precendence and override any corresponding properties specified in the configuration file.

Configuration Properties

This section provides information about each of the properties that are supported within a configuration file.

colorizeOutput

colorizeOutput: false

{
  "colorizeOutput": false
}

module.exports = {
  colorizeOutput: false
};

errorsOnly

errorsOnly: true

{
  "errorsOnly": true
}

module.exports = {
  errorsOnly: true
};

files

files:
  - file1.json
  - file2.yaml

{
  "files": [
    "file1.json",
    "file2.yaml"
  ]
}

module.exports = {
  files: [
    'file1.json',
    'file2.yaml'
  ]
};

ignoreFiles

    lint-openapi /my/apis/*.yaml --ignore /my/apis/broken-api.yaml

ignoreFiles:
  - /my/apis/file1.yml

{
  "ignoreFiles": [
    "/my/apis/file1.yml"
  ]
}

module.exports = {
  ignoreFiles: [
    '/my/apis/file1.yml'
  ]
};

limits

limits:
  warnings: 25

{
  "limits": {
    "warnings": 25
  }
}

module.exports = {
  limits: {
    warnings: 25
  }
};

logLevels

logLevels:
  root: error
  ibm-schema-description-exists: debug

{
  "logLevels": {
    "root": "error",
    "ibm-schema-description-exists": "debug"
  }
}

module.exports = {
  logLevels: {
    root: 'error',
    'ibm-schema-description-exists': 'debug'
  }
};

outputFormat

outputFormat: json

{
  "outputFormat": "json"
}

module.exports = {
  outputFormat: 'json'
};

ruleset

ruleset: my-custom-rules.yaml

{
  "ruleset": "my-custom-rules.yaml"
}

module.exports = {
  ruleset: 'my-custom-rules.yaml'
};

summaryOnly

summaryOnly: true

{
  "summaryOnly": true
}

module.exports = {
  summaryOnly: true
};

Validator Output

The validator can produce output in either text or JSON format. The default is text output, and this can be controlled with the -j/--json command-line option or outputFormat configuration property.

Text

Here is an example of text output:

IBM OpenAPI Validator (validator: 0.97.5; ruleset: 0.45.5), @Copyright IBM Corporation 2017, 2023.

Validation Results for /my/directory/my-api.yaml:

Errors:

  Message :   Path contains two or more consecutive path parameter references: /v1/clouds/{cloud_id}/{region_id}
  Rule    :   ibm-no-consecutive-path-parameter-segments
  Path    :   paths./v1/clouds/{cloud_id}/{region_id}
  Line    :   332

Warnings:

  Message :   Operation summaries should not have a trailing period
  Rule    :   ibm-summary-sentence-style
  Path    :   paths./v1/clouds.post.summary
  Line    :   46

  Message :   Operation summaries should not have a trailing period
  Rule    :   ibm-summary-sentence-style
  Path    :   paths./v1/clouds.get.summary
  Line    :   93

Summary:

  Total number of errors   : 1
  Total number of warnings : 2

  Errors:
   1 (100%) : Path contains two or more consecutive path parameter references

  Warnings:
   2 (100%) : Operation summaries should not have a trailing period

As you can see, any errors detected by the validator are listed first, then warnings, and finally a summary section. The -s/--summary-only command-line option or the summaryOnly configuration property can be used to request that only the summary is display. Also, the -e/--errors-only option or errorsOnly configuration property can be used to cause the validator to display only errors in the output.

JSON

When displaying JSON output, the validator will produce a JSON object which complies with this JSON schema. Here is an example of JSON output:

{
  "error": {
    "results": [
      {
        "message": "Path contains two or more consecutive path parameter references: /v1/clouds/{cloud_id}/{region_id}",
        "path": [
          "paths",
          "/v1/clouds/{cloud_id}/{region_id}"
        ],
        "rule": "ibm-consecutive-path-segments",
        "line": 332
      }
    ],
    "summary": {
      "total": 1,
      "entries": [
        {
          "generalizedMessage": "Path contains two or more consecutive path parameter references",
          "count": 1,
          "percentage": 100
        }
      ]
    }
  },
  "warning": {
    "results": [
      {
        "message": "Operation summaries should not have a trailing period",
        "path": [
          "paths",
          "/v1/clouds",
          "post",
          "summary"
        ],
        "rule": "ibm-summary-sentence-style",
        "line": 46
      },
      {
        "message": "Operation summaries should not have a trailing period",
        "path": [
          "paths",
          "/v1/clouds",
          "get",
          "summary"
        ],
        "rule": "ibm-summary-sentence-style",
        "line": 93
      }
    ],
    "summary": {
      "total": 2,
      "entries": [
        {
          "generalizedMessage": "Operation summaries should not have a trailing period",
          "count": 2,
          "percentage": 100
        }
      ]
    }
  },
  "info": {
    "results": [],
    "summary": {
      "total": 0,
      "entries": []
    }
  },
  "hint": {
    "results": [],
    "summary": {
      "total": 0,
      "entries": []
    }
  },
  "hasResults": true
}

The JSON output is also affected by the -s/--summary-only and -e/--errors-only options as well as the summaryOnly and errorsOnly configuration properties.

Logging

The validator uses a logger for displaying messages on the console. The core validator uses a single logger named root, while each of the rules contained in the IBM Cloud Validation Ruleset uses their own unique logger whose name will match the rule's id (e.g. ibm-accept-header, ibm-schema-description-exists, etc.).

Each logger has a logging level associated with it: error, warn, info, and debug. Each of these levels implicitly includes the levels that precede it in the list. For example, if you set the logging level of a logger to info, then all messages of type info, warn, and error will be displayed, but debug messages will not.

To set the level of the root logger to info, you could use this option: --log-level root=info.

To set the level of the logger used by the ibm-accept-header rule to debug, you could use this option: -l ibm-accept-header=debug.

You can also use a glob-like value for a logger name to set the level on multiple loggers. For example, to set the level for all loggers whose name starts with ibm-property, try this: -l ibm-property*=debug.

Enabling debug logging for a specific rule might be useful in a situation where the rule is reporting violations which seem to be inexplicable. In this case, additional debug information might be helpful in determining why the violations are occurring, and could possibly lead to a solution. For example, suppose the ibm-pagination-style rule is reporting several violations, but yet at first glance it's not obvious why these violations are occurring. To enable debug logging for this rule, use a command like this:

lint_openapi -l ibm-pagination-style=debug my-new-api.yaml

The default log level for the root logger is info, while the default log level for rule-specific loggers is warn.

Contributing

See CONTRIBUTING.

License

This project is licensed under Apache 2.0. Full license text is available in LICENSE.