About

Linter for a Swagger JSON API spec

Install

npm install --save swagger-lint-api

Usage

The library exposes validators to be used with an OpenAPI / Swagger JSON-formatted schema:

1. Require the library
2. Instantiate a new validator based on a schema
3. Invoke validator methods to validate the schema

Available validators to be used

| Validator Class | Validator functions | Description | | --------------- | ----------------------------------- | ----------------------------------------------------------------------------------------- | | Description | descriptionHasNoLineBreaks | assert no line breaks such as \n exist in the string | | Description | descriptionHasNoTabs | assert no tab control character exist in the string | | Description | descriptionEndsWithString(string) | assert the string ends with specific string | | Description | descriptionCompliesWithFunction(fn) | pass a custom function which expects a value to return true or false for custom assertion | | Paths | has2xxResponses | assert all paths have 2xx HTTP responses | | Paths | has4xxResponses | assert all paths have 4xx HTTP responses | | Paths | has5xxResponses | assert all paths have 5xx HTTP responses |

Example

Using a JSON schema file you want to validate:

const {DescriptionValidator} = require('swagger-lint-api')

// since it's just a JSON document we can require it into a variable
// and pass on to the constructor call
const mySwaggerSchema = require('./swagger-schema.json')
const validator = new DescriptionValidator(mySwaggerSchema)

// validate
const result = validator.descriptionHasNoLineBreaks()
// check result.valid being true or false

Inline JSON validation:

const {DescriptionValidator} = require('swagger-lint-api')

const someJSON = {description: 'this \n has \nline-breaks'}
const validator = new DescriptionValidator(someJSON)

// validate for line breaks
const result = validator.descriptionHasNoLineBreaks()
// result.valid will be false

Using it as a linting for a project:

1. Create a test file to run during lint / CI tests
2. Assert for expected structure in the Swagger JSON file

See example reference:

const {PathsValidator} = require('swagger-lint-api')
const assert = require('assert')

const mySwaggerExample = {
  swagger: '2.0',
  host: 'api.superheroes.io',
  basePath: '/v2',
  paths: {
    '/superheroes': {
      get: {
        summary: 'Finds superheroes',
        produces: ['application/json'],
        responses: {
          '200': {
            description: 'successful operation',
            schema: {
              type: 'array',
              items: {
                $ref: '#/definitions/SuperHeroes'
              }
            }
          }
        }
      }
    }
  }
}

const validator = new PathsValidator(mySwaggerExample)
const actual = validator.has4xxResponses()
const expected = {valid: true}

assert.deepStrictEqual(actual, expected)
// will throw an error and print it on console
// due to mySwaggerExample object missing a
// 4xx response type

Contributing

Please consult CONTIRBUTING for guidelines on contributing to this project.

Author

swagger-lint-api © Liran Tal, Released under the Apache-2.0 License.