antonk52 / swaggerlint

Keep your API consistent

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

Documentation

• How to write a rule

Acknowledgments

This tool has been inspired by already existing swagger validation checkers:

• api lint
• speccy
• zally
• openapi-validator