https://github.com/lirantal/swagger-lint-api

Linter for a Swagger JSON API spec
https://github.com/lirantal/swagger-lint-api

api lint linter openapi swagger

Last synced: 7 days ago
JSON representation

Linter for a Swagger JSON API spec

• Host: GitHub
• URL: https://github.com/lirantal/swagger-lint-api
• Owner: lirantal
• License: apache-2.0
• Created: 2019-07-01T21:13:02.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2022-04-07T18:23:39.000Z (over 2 years ago)
• Last Synced: 2024-11-02T14:42:38.188Z (14 days ago)
• Topics: api, lint, linter, openapi, swagger
• Language: JavaScript
• Size: 896 KB
• Stars: 3
• Watchers: 2
• Forks: 5
• Open Issues: 8
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md

Awesome Lists containing this project

README

        


  swagger-lint-api





  Linter for a Swagger JSON API spec





  

  

  

  

  

  

  



# About

Linter for a Swagger JSON API spec

# Install

```bash

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:

```js

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:

```js

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:

```js

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](./CONTRIBUTING.md) for guidelines on contributing to this project.

# Author

**swagger-lint-api** © [Liran Tal](https://github.com/lirantal), Released under the [Apache-2.0](./LICENSE) License.