@naturacosmeticos/api-linter

A comprehensive API linter for swagger files using OpenAPI 3.0 following Natura Cosmeticos best practices

Installation

# with npm
npm install --save @naturacosmeticos/api-linter

# with yarn
yarn add @naturacosmeticos/api-linter

Usage

const path = require('path');
const { validate } = require('@naturacosmeticos/api-linter');

const swaggerFile = path.join('path', 'to', 'swagger', 'file.yml');

/**
 * Optional rules object for disabling/enabling rules
 */
const options = {
  "must-contain-port": true,
  "must-contain-server-url": true,
  "no-singular-resource": true,
  "must-contain-version": true,
  "must-contain-domain-and-context": true,
  "resource-spinal-case": true,
  "no-custom-media-type": true,
  "must-contain-media-type-version": true
};

const promise = validate(swaggerFile, options);

promise.then(faults => {
  console.log(faults);
}).catch(err => {
  console.error(err);
});

CLI

$ npm install -g @naturacosmeticos/api-linter

$ api-linter --help ## For options

$ api-linter --file=/path/to/swagger.yml ## Basic usage

Rules

These are the rules checked by the linter

{
  /**
   * Checks for missing port number on server url, defaults to `true`
   */
  "must-contain-port": boolean;
  /**
   * Checks for server url properties, defaults to true
   */
  "must-contain-server-url": boolean;
  /**
   * Allow resource names in singular, defaults to `true`
   */
  "no-singular-resource": boolean;
  /**
   * Checks for missing version number on server url, defaults to `true`
   */
  "must-contain-version": boolean;
  /**
   * Checks for missing `/domain/context` on server url, defaults to `true`
   */
  "must-contain-domain-and-context": boolean;
  /**
   * Checks for resources not using spinal case
   */
  "resource-spinal-case"?: boolean;
  /**
   * Checks for main media types defined in RFC 6838, defaults to `true`
   */
  "no-custom-media-type"?: boolean;
  /**
   * Checks for the presence of version parameter on vendor specific media types
   */
  "must-contain-media-type-version"?: boolean;
}