openapi-enforcer

OpenAPI-Enforcer

Tools for using the Open API Specification (OAS)

Supports OAS 2.0 (formerly Swagger) and OAS 3.x.x

Features

• Create an API.
• Validate your OAS documents.
• Serialize, deserialize, and validate values against OAS schemas.
• Identify the operation associated with a request.
• Parse, deserialize, and validate request parameters.
• Facilitated response building.
• Generate random valid values for a schema.
• Plugin environment for custom document validation and extended functionality including custom data type formats.

Website - openapi-enforcer.com

Installation

npm install openapi-enforcer

Examples

Loading and Validating a Document

Use the Enforcer to load and resolve all $ref values and then to validate the complete document.

const Enforcer = require('openapi-enforcer')

async function run () {
  const [openapi, error, warning] = await Enforcer('./path/to/openapi.yml', {
    fullResult: true
  })
  if (error !== undefined) console.error(error)
  if (warning !== undefined) console.warn(warning)
  if (openapi !== undefined) console.log('Document is valid')
}

run.catch(console.error)

Processing an Incoming Request

const Enforcer = require('openapi-enforcer')

async function run () {
  // Because we don't specify `fullResult: true`, any errors will throw an exception and
  // warnings will be logged to the console.
  const openapi = await Enforcer('./path/to/openapi.yml')

  // If the request is valid then the req object will contain the parsed and validated request.
  // If it is invalid then the error will contain details about what was wrong with the
  // request and these details are safe to return to the client that made the request.
  const [ req, error ] = openapi.request({
    method: 'POST',
    path: '/tasks',
    // the body should be parsed by a JSON.parse() prior to passing in (if applicable).
    body: { task: 'Buy Milk', quantity: 2 }
  })

  // You can use the req.operation property to look at the properties from your OpenAPI document.
  // A good use of this is to look at the operationId you defined there to determine which path
  // is being used to handle the request.
  if (req.operaton.operationId === 'my-operation-id') {
    // ... additional request processing
  }
}

run.catch(console.error)

Producing a Valid Result

const Enforcer = require('openapi-enforcer')

async function run () {
  const openapi = await Enforcer('./path/to/openapi.yml')

  const [ req ] = openapi.request({
    method: 'POST',
    path: '/tasks',
    // the body should be parsed by a JSON.parse() prior to passing in (if applicable).
    body: { task: 'Buy Milk', quantity: 2 }
  })

  const body = { id: 1, task: 'Buy Milk', quantity: 2, dateCompleted: null }
  const headers = {}

  // This will validate the response code, body, and headers. It will also correctly serialize
  // the body and headers for sending to the client that made the request. Using this method
  // you'll never send back a response that does not match what your OpenAPI document defines.
  const [ res, error ] = req.response(200, body, headers)
  console.log(res.body, res.headers)
}

run.catch(console.error)

Changelog

1.18.0

Added

• Case Sensitivity Optional For Paths

  The default behavior is for paths to be case sensitive. There is now an option Enforcer.config.useCaseSensitivePaths (defaulting to true) that when set to false will change how paths duplicates are validated and how paths are looked up when attempting to match a path to a request.