Swaggerlint NPM

Swaggerlint

Swaggerlint helps you to have a consistent API style by linting your swagger / OpenAPI Scheme.

Installation

Install it in your project

npm install swaggerlint

Install it globally

npm install --global swaggerlint

Usage

CLI

You can lint your swagger scheme by path

swaggerlint /path/to/swagger.json

Or by providing a URL

swaggerlint https://...

Config flag

swaggerlint will automatically search up the directory tree for a swaggerlint.config.js file. Or you can specify it explicitly

swaggerlint --config /path/to/swaggerlint.config.js

Nodejs

const {swaggerlint} = require('swaggerlint');
const config = require('./configs/swaggerlint.config.js');
const swaggerScheme = require('./swagger.json');

const result = swaggerlint(swaggerScheme, config);

console.log(result); // an array or errors

/**
 * [{
 *   name: 'string', // rule name
 *   msg: 'string', // message from the rule checker
 *   location: ['path', 'to', 'error'] // what caused an error
 * }]
 */

Docker image

If you do not have nodejs installed you can use the swaggerlint docker image.

Config

// swaggerlint.config.js
module.exports = {
    rules: {
        'object-prop-casing': ['camel'],
        'properties-for-object-type': true,
        'latin-definitions-only': true,
    },
};

Rules

You can set any rule value to false to disable it or to true to enable and set its setting to default value.

rule name	description	default
`expressive-path-summary`	Enforces an intentional path summary
`latin-definitions-only`	Bans non Latin characters usage in definition names	["placeholder_to_be_removed",{"ignore":[]}]
`no-empty-object-type`	Object types have to have their properties specified explicitly
`no-external-refs`	Forbids the usage of external ReferenceObjects
`no-inline-enums`	Enums must be in `DefinitionsObject` or `ComponentsObject`
`no-ref-properties`	Disallows to have additional properties in Reference objects
`no-single-allof`	Object types should not have a redundant single `allOf` property
`no-trailing-slash`	URLs must NOT end with a slash
`object-prop-casing`	Casing for your object property names	"camel"
`only-valid-mime-types`	Checks mime types against known from `mime-db`
`parameter-casing`	Casing for your parameters	"camel",{"header":"kebab"}
`path-param-required-field`	Helps to keep consistently set optional `required` property in path parameters
`required-operation-tags`	All operations must have tags
`required-parameter-description`	All parameters must have description
`required-tag-description`	All tags must have description