@overspeed/koa2-oas3
v0.0.5
Published
Koa2 OpenAPI 3 request validation middleware.
Downloads
8
Readme
OpenAPI 3 Koa 2 Request Validation Middleware
Requirements
Node.js Version 8+
OpenAPI 3
Koa2
Usage
const koa2OA3 = require('@overspeed/koa2-oas3');
const _ = require('koa-route');
const Koa = require('koa');
const app = new Koa();
const specUri = 'https://api.swaggerhub.com/apis/overspeedio/Koa2Oas3Example/1.0.0';
// default options
const koa2OA3Options = {
mergeRemoteRefs: false,
renderDocs: true,
docsPath: '/docs'
};
// apply middleware
koa2OA3(app, specUri, koa2OA3Options)
.then(() => {
app.use(_.get('/pet/:id', (ctx, id) => {
ctx.body = {
id,
name: 'tobi'
};
}));
app.listen(3000);
console.log('listening');
})
.catch((e) => {
console.error(e);
});
koa2OA3 Function Params
| Name | Type | Required | Description | |-----------|-------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------| | app | Koa2 App Instance | true | A Koa2 app instance you want the middleware to be applied to. | | specOrUri | String / Object | true | Either a URI to a swagger specification Koa2-OAS3 can grab down and apply, or a JavaScript object that contains the OpenAPI3 specification. | | options | Object | false | Custom options to pass to the middleware, see all options below. |
Allowed Options and Defaults
| Option | Type | Default | Description | |-----------------------------|----------|-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | mergeRemoteRefs | Boolean | false | OpenAPI 3 allows you to reference from other api specifications based on a URI. This option will reach out to these different refs and merge the definitions into the provided API spec. | | renderDocs | Boolean | true | This renders a UI to visualize the OpenAPI specification. | | docsPath | String | /docs | What path should the docs be rendered at. In addition a second route will be rendered {docsPath}/spec that responds with the api specification in JSON format. | | docsSuupportedSubmitMethods | Array | ['get', 'post', 'put', 'delete', 'patch'] | In the DOC's interactive interface example requests can be submitted to the configured API spec remotes. This allows adding limitations on the feature. | | docsJsonEditor | Boolean | false | Should the JSON editor be visible in the render documentation view. | | docsShowRequestHeaders | Boolean | false | https://www.npmjs.com/package/koa2-swagger-ui | | docsHideTopbar | Boolean | true | https://www.npmjs.com/package/koa2-swagger-ui | | docsAuthOptions | Object | {} | https://www.npmjs.com/package/koa2-swagger-ui | | docDdefaultModelRendering | String | schema | https://www.npmjs.com/package/koa2-swagger-ui | | handleError | Function | See below code snippet | |
Default Error Handle
const handleError = ({ code, location, message }) => {
return {
errors: [{
status: `${code}`,
title: 'Request Validation Error',
detail: message,
source: location
}]
};
}