Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Gi60s/openapi-enforcer
https://github.com/Gi60s/openapi-enforcer
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/Gi60s/openapi-enforcer
- Owner: Gi60s
- License: apache-2.0
- Created: 2018-02-05T23:06:16.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-03-02T00:36:54.000Z (10 months ago)
- Last Synced: 2024-08-07T20:58:51.173Z (4 months ago)
- Language: JavaScript
- Size: 4.53 MB
- Stars: 94
- Watchers: 7
- Forks: 22
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://openapi-enforcer.com/)
## Installation
```shell
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.
```js
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
```js
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
```js
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)
```