Node.js linter for OpenAPI specs
Branch: master
Clone or download
Latest commit 8f3e324 Sep 13, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add PR template Nov 1, 2017
docs Standardize EOF newlines Sep 12, 2018
lib Add nested property support (#52) Sep 12, 2018
test Add nested property support (#52) Sep 12, 2018
.eslintrc.json Custom improvements (#23) Dec 1, 2017
.gitignore Ignore npm log files Jul 28, 2017
.npmrc Add npmrc file to point to public npm Oct 8, 2017
.nvmrc Initial version Jul 26, 2017
.releasinator.rb Wait for correct npm version Oct 8, 2017
.travis.yml Update notifications url Jul 31, 2017
CHANGELOG.md
CONTRIBUTING.md Add releasinator (#4) Aug 21, 2017
Gemfile Add releasinator (#4) Aug 21, 2017
Gemfile.lock
LICENSE Initial version Jul 26, 2017
README.md Edit readme with better description Dec 1, 2017
Rakefile Add releasinator (#4) Aug 21, 2017
package.json Prepare for 0.10.0 Sep 12, 2018

README.md

NPM version build status Downloads

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 coming shortly.

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.