isabella232 / openapilint

Node.js linter for OpenAPI specs

openapilint

This project uses Node.js to implement an OpenAPI linter. As with any linter, there are configurable options for validating your OpenAPI specs.

Install openapilint

npm install openapilint --save

Usage

openapilint takes as input a json schema, and json config object:

const schema = {
  info: {
    description: 'handy description'
  }
};
const config = {
  "rules": {
    "docs-path": true,  // rule will be run, and has no special config
    "no-restricted-words": {"words": ["supersecretacronym"]},  // rule will be run with the specified config
    "root-tags": false // rule will not be run
  }
};

and returns a promise of the results:

const result = new OpenApiLint(config).lint(schema);

return result.then((lintResult) => {
  // Do something with the result Map.
}).catch((error) => {
  // Do something with the Error.
});

lintResult is a String -> RuleResult immutable Map of nested immutable objects for consumption. Specifically:

• RuleResult is a String -> Object immutable Record with two keys, description (String) & failures (List<RuleFailure>).
• RuleFailure is a String -> String immutable Record with two keys, location (String) & hint (String)

It is up to the implementer to parse this data and provide a useful error response to the user.

Rules

By default, only the rules in lib/rules are supported. Details of these rules can be found in docs/rules.

Dereferencing

Due to the complex nature of multi-file references, openapilint rules assume that all references are contained within the input. For simplicity, references to anything other than internally are treated as errors.

OpenAPI supported versions

openapilint supports Swagger 2.0. Support for OpenAPI 3.0 is not planned.

Comparison to other validators

openapilint does have some overlapping features with other json validators, such as joi and jsonschema. A developer using this project may choose to use those validators as a first wave of checks against a particular spec before running it through the openapilint set of rules. This is expected and encouraged. The rules implemented within openapilint go above and beyond those validators by targeting the common OpenAPI-specific problems.

License

See License.

Contributing

See Contributing.

Acknowledgements

This project was inspired by - and heavily influenced by - eslint, markdownlint, and swagger-api-checkstyle. The configuration schema and some code was modified for usage in this project.