OpenAPI Specification can be used to secure and accelerate the API lifecycle.

OpenAPI is now a widely-adopted method for describing web APIs. With that fact comes the pressure to validate these specifications are up to date, accurately constructed, and presented for optimal developer usage.

Especially with the shift from OpenAPI v2 to v3, developers may require further assistance to ensure their specification matches the current v3 structure and format. Thankfully, there are plenty of open source tools developers can use to lint their API specification against OpenAPI v3 as well as best practices and custom rules.

In this article, we showcase select open source API linters that validate your YAML and JSON schemas for OpenAPI v3. Validating that APIs specs are to … spec… will bring better usability, helping you to get the most out of your OpenAPI adoption.

What is Linting? What is API Linting?

Linting is the process of validating code is constructed as expected. This is typically initiated against an established set of rules.

“A linter or lint refers to tools that analyze source code to flag programming errors, bugs, stylistic errors, and suspicious constructs” – lint (software)

Thus, API linting is the process of validating APIs. With OpenAPI now the most widely adopted specification format for describing REST APIs, developers must ensure their schemas meet the spec. To help with this process, we’ve researched 8 free open source tools to lint your OpenAPI specifications against v3.

1: Speccy

Enforce quality rules on your OpenAPI 3.0.x specifications

Speccy ensures a specification is valid against OpenAPI v3, and also lints it against certain established rules. Speccy is initiated with usable CLI commands: lint, resolve, and serve. Further options extend its linting capabilities to follow certain rules; such as -v, which detects verbosity.

An OpenAPI spec with missing information may still technically be considered “valid.” Therefore, Speccy’s default rules assure common-sense fields are filled, such as descriptions for parameters or contact information. It also allows the creation of custom rules.

In addition to linting, Speccy has other helpful functionalities. For example, its Resolve command will combine multiple files into a single spec. Speccy also integrates with ReDoc to visualize API documentation. With all this developer usability, Speccy is a useful toolkit that goes beyond simple specification validation.

2: oas-kit

An OpenAPI utility to convert/resolve/validate/lint

Oas-kit is an open source utility for converting Swagger 2.0 definitions to OpenAPI 3.0, and validating and linting such documents. Based on a similar tech to Speccy, the package oas-linter provides an easy set of rules for API linting. You can view the Options documentation here for specific object parameters.

3: zally

A minimalistic, simple-to-use OpenAPI 2 and 3 linter

Maintained by Zalando, zally is an open source tool for linting APIs against OpenAPI v2 and v3. Out-of-the-box, zally will validate APIs against Zalando’s REST guidelines, however, this can be reconfigured if necessary. Zallly comes equipped with a range of implementation options: RESTful API, CLI, and a web interface.

4: spectral

A flexible JSON object linter w/ OpenAPI v2 and v3 support

A key aspect of Spectral, the linter developed by Stoplight, is its flexibility. Spectral allows you to create custom rules to lint JSON objects. Such rules can be developed to apply to certain parts of the JSON objects. Though customization is possible, Spectral can leverage existing rulesets to validate and lint OpenAPI versions 2 and 3. The two main components of Spectral are rules and functions, which effectively generate a “flexible and customizable style guide for your JSON objects.” For even greater usability, Taylor Barnett has also constructed a Spectral Bo that lints an OpenAPI Spec given a Github pull request.

5: openapi-lint

OpenAPI v3 linter with features for Visual Studio users

Openapi-lint provides a method to convert between OpenAPI v2 and v3, and offers an ability to validate and lint OpenAPI 3.0.x documents. Openapi-lint is a helpful extension for Microsoft Visual Studio (VS) users, as it comes pre-configured with VS commands.

6: openapilint

Node.js linter for OpenAPI specs

Developed by Braintree, openapilint is an open source utility that uses Node.js to validate APIs against the OpenAPI Specification standard. It takes a JSON object or schema as input, analyzes it against this default set of rules, and responds with useful error messages. Though openapilint shares some qualities with other JSON schema validators, it purportedly goes “above and beyond those validators by targeting the common OpenAPI-specific problems.”

7: OpenAPI Spec validator

Straightforward OpenAPI v2 and v3 validation

Written in Python, the OpenAPI Spec validator library validates an OpenAPI spec for both v2 and v3. It can validate a spec directly or by specifying a URL. The tool is developed by Artur Maciag and released under Apache v2.

A command to validate a spec using OpenAPI Spec validator looks like the following:

from openapi_spec_validator import validate_spec

validate_spec(spec_dict)

8: oval

CLI for OpenAPI Specification document validation.

Developers that want a simple, programmatic OpenAPI spec validation tool will enjoy oval, a utility maintained by Jeremy Whitlock of Google. It’s built on top of Sway and provides comprehensive OAS coverage. “Plans for oval are to provide an eslint-like experience for OAS validation in the future.”

Some example CLI commands are as follows:

USAGE
  $ oval validate LOCATION

ARGUMENTS
  LOCATION  The path/URL to the OAS document being validated

OPTIONS
  -N, --no-color            turn off colored output
  -j, --json                output results as JSON
  -p, --print-success       print message for success
  -w, --warnings-as-errors  treat warnings as errors

Honorable Mentions:

• Kaizen OpenAPI Parser
• Linter-swagger by Atom
• APIs.guru cites that an API Linter is under development
• API Lint
• APIDevTools swagger-parser
• IBM OpenAPI Validator

Options For OpenAPI Linting

OpenAPI comes with many benefits, however, there is little point in adopting the standard if no quality assurances are made. For REST API developers using OpenAPI, linting utilities help dilute the pain. Having such a tool in the continuous build and publish lifecycle could certainly help organizations maintain a large number of OpenAPI-fueled services.

Linting will ensure that metadata, servers, paths, parameters, as well as request bodies and response bodies, are accurately depicted. Once validated with API linting in full force, OpenAPI definitions can truly reach their full potential.

Of course, there are practical linting tools for all programming languages, like CSS LINT, JSHint, JSLint, and Pylint. API developers specifically looking for JSON schema validators may also benefit from bookmarking JSONLint, joi, or jsonschema; these tools can assure JSON is validated and formatted correctly.