superfaceai / openapi-linter

Is your OpenAPI Spec ready for SDK generators?

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, but any client code generator benefits from well written OpenAPI specs.

Setup

Install from npm globally:

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 <file or URL>

CLI commands

• openapi-linter lint SPECIFICATIONPATH

openapi-linter lint SPECIFICATIONPATH

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=<option>     [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.
                             <options: error|warning|any>
  -f, --fileFormat=<option>  Format of specification. Must be "yaml" or "json" when defined
                             <options: yaml|json>

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:

npm i @superfaceai/openapi-linter

Use the lint function:

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.

© 2023 Superface s.r.o.