node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



Build Status Coverage Status Known Vulnerabilities

Make sure your OpenAPI 3.0 specifications are more than just valid, make sure they're useful!

Taking off from where Mike Ralphson started with linting in swagger2openapi, Speccy aims to become the rubocop or eslint of OpenAPI.

OpenAPI Specification

Currently tracking v3.0.0

If you want to run speccy on OpenAPI (f.k.a Swagger) v2.0 specs, run it through swagger2openapi first and speccy can give advice on the output.


Usage: speccy <command>


  -V, --version  output the version number
  -h, --help     output usage information


  lint [options] <file-or-url>
  resolve [options] <file-or-url>
  serve [options] <file>

Lint Command

The goal here is to sniff your files for potentially bad things. "Bad" is objective, but you'll see validation errors, along with special rules for making your APIs better..

Usage: lint [options] <file-or-url>

Ensure your OpenAPI files are valid and up to scratch


    -r, --rules [ruleFile]  use this multiple times to select multiple rules files
    -s, --skip [ruleName]   use this multiple times to skip specific rules
    -h, --help              output usage information

You'll see output such as:

#/info  R: info-contact  D: info object should contain contact object

expected Object {
  version: '5.0',
  title: 'Foo API'
} to have property contact

There are going to be different things people are interested in, so the default rules suggest things we think everyone should do; adding descriptions to parameters and operations, and having some sort of contact info.

There are strict rules which demand more contact details, "real" domains, a license, and requires tags have a description!

There are also wework rules, building things we consider important on top of the strict rules; keeping summaries short (so they fit into ReDoc navigation for example).


Rule actions from the default rules will be used if no rules file is specified. Right now there are only the three bundled options, but supporting custom rules files via local path and URL is on the roadmap.

Contributions of rules and rule actions for the linter are very much appreciated.

Serve Command

Using ReDoc and the handy utility redocup, speccy can offer a preview of your specifications, in human-readable format. In the future we'll have speccy outlining improvements right in here, but one thing at a time ey?

Usage: serve [options] spec-json-or-yaml-path

View specifications in beautiful human readable documentation


  -p, --port [value]  port on which the server will listen (default: 5000)
  -w, --watch         reloding browser on spec file changes
  -h, --help          output usage information

Like everything in speccy, this only works for OpenAPI v3.


To run the test-suite:

npm test



BSD-3-Clause except the openapi-3.0.json schema, which is taken from the OpenAPI-Specification and the alternative gnostic-3.0.json schema, which is originally from Google Gnostic. Both of these are licensed under the Apache-2 license.