This project uses Node.js to implement an OpenAPI linter. As with any linter, there are configurable options for validating your OpenAPI specs.
npm install openapilint --save
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:
RuleResultis aString -> Objectimmutable Record with two keys,description(String) &failures(List<RuleFailure>).RuleFailureis aString -> Stringimmutable 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.
By default, only the rules in lib/rules are supported. Details of these rules can be found in docs/rules.
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.
openapilint supports Swagger 2.0. Support for OpenAPI 3.0 is not planned.
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.
See License.
See Contributing.
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.