Skip to content

antonk52/swaggerlint

Repository files navigation

Swaggerlint

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

npm command

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

Acknowledgments

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