swagger-lint-api

Linter for a Swagger JSON API spec

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.