Designing OpenAPI specifications is hard. The format was originally intended to be machine-readable but has become the standard for discussing APIs in human-to-human interactions as well. This often leads to humans having to edit and maintain OpenAPI files by hand.

OpenAPI files are no different from other code artifacts. We generally want to focus on structure, consistency, and readability.

To assess the quality and validity of our OpenAPI contracts we can use linters. In this post, I'm exploring the most popular options for OpenAPI-based linters: Vaccum, RateMyOpenAPI, and Spectral.

#1. Vacuum

Link to Vacuum

Vacuum describes itself as:

The world's fastest OpenAPI & Swagger linter.

It's a battle-tested linter written in Go that focuses on speed and easy integration into existing CI/CD pipelines.

#Pros:

• Customize Rules: Define and configure rules to fit the guidelines of your organization.
• Quick: Vacuum blazingly fast which makes it great in CI environments.
• Group errors: Vacuum groups errors allowing for easy display and message consumption.
• Free & Open Source: The product is free and open-source

#2. RateMyOpenAPI

Link to RateMyOpenAPI

RateMyOpenAPI is a tool developed by Zuplo, a fairly new API Gateway based on OpenAPI. RateMyOpenAPI is published as a library, CLI, and Web Interface. The latter makes it easy to get started. Simply visit the website, paste your OpenAPI file and see the result.

#Pros:

• Receive a grade: RateMyOpenAPI assigns a grade to your OpenAPI contract making it simple to understand the overall quality and validity of your file.
• Free & Open Source: The product is free and open-source

#3. Spectral

Spectral is a well-known OpenAPI linter made by the engineers behind Stoplight. It includes custom and default rulesets based on API-Styleguides (a concept native to Stoplight).

#Pros:

• Robust and tested: Stoplight has been around for a long time and has great support for most OpenAPI features and formats. So does its linter.
• Flexible styleguides: Design your linting process around default and reusable style guides

#Choosing the Best OpenAPI Linter

Linting is an essential process for working with OpenAPI files. It can be a helpful if your process involves manually editing OpenAPI specifications or relying on them in CI/CD pipelines. Most linters offer similar functionality, performance, and extensibility making it hard to recommend one over the other.

If you are looknig for a way to generate, manage, evolve professional API contracts, check out api-fiddle.