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