OpenAPI Linter


> Is your OpenAPI Spec ready for SDK generators?

OpenAPI Linter is a CLI and a Node.js library to validate OpenAPI specification.
It is based on [Spectral] by Stoplight with OpenAPI rules with additional rules. The goal of Linter is to check whether the spec contains enough information to generate high quality, well documented SDK.
We use OpenAPI Linter in [Superface Integration Designer][designer], but any client code generator benefits from well written OpenAPI specs.

Setup

Install from npm globally:

``shell
npm i -g @superfaceai/openapi-linter
`

Now you can use the linter with commands openapi-linter or oal.

Alternatively you can use the linter without installation with npx:

`
npx @superfaceai/openapi-linter lint
`

CLI commands

- openapi-linter lint SPECIFICATIONPATH

$3

Lints OpenAPI specification using three different parsers/validators.

`
USAGE
$ openapi-linter lint [SPECIFICATIONPATH] [-f yaml|json] [-e error|warning|any]

ARGUMENTS
SPECIFICATIONPATH Path or URL to specification file

FLAGS
-e, --throwOn= [default: error] On which kind of severty error should be thrown. When set to warning
command will throw when there is a result with "warning" or "error" severity.

-f, --fileFormat= Format of specification. Must be "yaml" or "json" when defined


DESCRIPTION
Lints OpenAPI specification using three different parsers/validators.

EXAMPLES
$ oal lint https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml

$ oal lint examples/petstore.yaml

$ oal lint examples/petstore.yaml -e any

$ oal lint examples/petstore.yaml -f yaml
`

Usage in code

Install the linter as a dependency into your project:

`shell
npm i @superfaceai/openapi-linter
`

Use the lint function:

`ts
import { lint } from 'openapi-linter';

// Get specification as string
const specification = await fs.readFile(pathToSpec, { encoding: 'utf-8' });

// Pass specification, its extension ("yaml" or "json") and name
const lintResult = await lint(specification, 'yaml', 'my-spec-name');

//Do something with result
console.log(lintResult);
``

Related projects

- [Spectral], generic linter for JSON and YAML this project is based on
- OpenAPI Enforcer
- OpenAPI Validator
- OAS Tools
- Redocly CLI
- Cherrybomb (Rust)
- and many more

Maintainers

- Jakub Vacek
- Radek Kyselý

License

This project is licensed under the MIT license.

© 2022 Superface s.r.o.

[spectral]: https://stoplight.io/open-source/spectral
[designer]: https://superface.ai/designer