Vale & The OpenAPI Specification
Published in
4 min readSep 25, 2019
OpenAPI Specification files provide machine-readable (JSON or YAML) descriptions of APIs and often contain snippets of text suitable for linting.
The problem is that the target text can be hard to reach from a linting perspective. For instance, consider the following basic example:
As you can see above, the only parts we’re really interested in are the title, description (which can contain Markdown), and summary keys.
In the following sections, we’ll discuss the three main techniques for linting specification files using Vale (an open-source linter for prose). For the examples, we’ll be referencing the petstore.yaml file from Swagger.
Option 1: No Processing
The easiest way to lint an OpenAPI specification file is to simply pass it, as is, to Vale:
