Skip to content

superfaceai/openapi-linter

Repository files navigation

OpenAPI Linter

GitHub Workflow Status npm license CLI built with oclif GitHub Discussions

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

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

Maintainers

License

This project is licensed under the MIT license.

© 2023 Superface s.r.o.