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 - @rtyughnnpm/minima-et-soluta.com

Installation

1npm install @rtyughnnpm/minima-et-soluta

Examples

Loading and Validating a Document

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

1const Enforcer = require('@rtyughnnpm/minima-et-soluta')
2
3async function run () {
4  const [openapi, error, warning] = await Enforcer('./path/to/openapi.yml', {
5    fullResult: true
6  })
7  if (error !== undefined) console.error(error)
8  if (warning !== undefined) console.warn(warning)
9  if (openapi !== undefined) console.log('Document is valid')
10}
11
12run.catch(console.error)

Processing an Incoming Request

1const Enforcer = require('@rtyughnnpm/minima-et-soluta')
2
3async function run () {
4  // Because we don't specify `fullResult: true`, any errors will throw an exception and
5  // warnings will be logged to the console.
6  const openapi = await Enforcer('./path/to/openapi.yml')
7
8  // If the request is valid then the req object will contain the parsed and validated request.
9  // If it is invalid then the error will contain details about what was wrong with the
10  // request and these details are safe to return to the client that made the request.
11  const [ req, error ] = openapi.request({
12    method: 'POST',
13    path: '/tasks',
14    // the body should be parsed by a JSON.parse() prior to passing in (if applicable).
15    body: { task: 'Buy Milk', quantity: 2 }
16  })
17
18  // You can use the req.operation property to look at the properties from your OpenAPI document.
19  // A good use of this is to look at the operationId you defined there to determine which path
20  // is being used to handle the request.
21  if (req.operaton.operationId === 'my-operation-id') {
22    // ... additional request processing
23  }
24}
25
26run.catch(console.error)

Producing a Valid Result

1const Enforcer = require('@rtyughnnpm/minima-et-soluta')
2
3async function run () {
4  const openapi = await Enforcer('./path/to/openapi.yml')
5
6  const [ req ] = openapi.request({
7    method: 'POST',
8    path: '/tasks',
9    // the body should be parsed by a JSON.parse() prior to passing in (if applicable).
10    body: { task: 'Buy Milk', quantity: 2 }
11  })
12
13  const body = { id: 1, task: 'Buy Milk', quantity: 2, dateCompleted: null }
14  const headers = {}
15
16  // This will validate the response code, body, and headers. It will also correctly serialize
17  // the body and headers for sending to the client that made the request. Using this method
18  // you'll never send back a response that does not match what your OpenAPI document defines.
19  const [ res, error ] = req.response(200, body, headers)
20  console.log(res.body, res.headers)
21}
22
23run.catch(console.error)