README.md

jest-runner-oas-linter

A Jest runner for oas-linter.

It's easy enough to run something like speccy, but for integration with CI having something that provides more structured output (e.g. by using jest-unit and Jest) a more machine friendly output can be produced and you can take advantage of other useful features like file watching.

Additionally Speccy doesn't support JS modules, which is a pain if you like writing your API documents like that - the underlying oas-linter has no problem though.

Note that this module does not directly support YAML, but can by adding a wrapper file that parses your YAML and linting that instead, e.g. install yaml and then create an api.js to lint, e.g.

const fs = require('fs')
const YAML = require('yaml')

const file = fs.readFileSync('./file.yml', 'utf8')
module.exports = YAML.parse(file)

Warning

This is very alpha; no tests have been written, no promises made, YMMV.

Compatibility

This module is compatible with Node v8.x and upwards. Any incompatibilities with those versions should be reported as bugs.

Usage

Install

Install jest(it needs Jest 21+) and jest-runner-oas-linter

npm install --save-dev jest jest-runner-oas-linter

# or with Yarn

yarn add --dev jest jest-runner-oas-linter

Add your runner to Jest config

Once you have your Jest runner you can add it to your Jest config. You will almost certainly want to configure separate Jest projects and only use this runner on modules that export an OpenAPI document.

Recommended Steps

Create separate configuration files for each "project" (e.g. tests, eslint, and api document linting) and then reference them in your package.json.

In your package.json

{
  "jest": {
    "projects": [
      "<rootDir>/jest-test.config.js",
      "<rootDir>/jest-eslint.config.js",
      "<rootDir>/jest-oas-linter.config.js"
    ]
  }
}

In your jest-oas-linter.config.js

module.exports = {
  runner: 'oas-linter',
  displayName: 'oas-linter',
  testMatch: [
    '<rootDir>/path/to/your/api/doc.js',
    '<rootDir>/path/to/another/api/doc.js',
    '<rootDir>/path/to/another/api/doc/**/*.js',
  ],
}

Minimal Steps

These are the more standard steps to set up a test runner

In your package.json

{
  "jest": {
    "runner": "oas-linter",
    "testMatch": ["<rootDir>/path/to/your/api/doc.js"]
  }
}

Or in jest.config.js

module.exports = {
  runner: 'oas-linter',
  testMatch: ['<rootDir>/path/to/your/api/doc.js'],
};

Configure OAS Linter

Configuration can be specified in your project root in .oaslintrc.json, or in an oaslintConfig in the package.json file.

Currently the only two options are to specify whether the default rules should be loaded with loadDefaultRules and to specify additional rules to be applied.

• loadDefaultRules is boolean and defaults to true, oas-linter default rules can be seen over there
• rules is an array of objects, as per oas-linter's applyRules. More details about the format of rules supported can be found over at oas-kit's linter rules documentation and the default rules (link above) have many examples.

In your package.json

{
  "oaslintConfig": {
    "loadDefaultRules": true,
    "rules": [
      {
        "name": "schema-property-require-description",
        "object": "schema",
        "description": "schema properties must have a description",
        "truthy": "description"
      }
    ]
  }
}

Or in .oaslintrc.json

{
  "loadDefaultRules": true,
  "rules": [
    {
      "name": "schema-property-require-description",
      "object": "schema",
      "description": "schema properties must have a description",
      "truthy": "description"
    }
  ]
}

Run Jest

npx jest
# or with Yarn
yarn jest