https://github.com/confuser/exegesis-koa
Koa middleware to handle OpenAPI 3.x.
https://github.com/confuser/exegesis-koa
koa middleware nodejs openapi openapi3
Last synced: 4 months ago
JSON representation
Koa middleware to handle OpenAPI 3.x.
- Host: GitHub
- URL: https://github.com/confuser/exegesis-koa
- Owner: confuser
- License: mit
- Created: 2018-06-03T11:48:14.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-05T04:35:38.000Z (about 1 year ago)
- Last Synced: 2025-08-18T18:58:47.480Z (6 months ago)
- Topics: koa, middleware, nodejs, openapi, openapi3
- Language: JavaScript
- Size: 657 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# exegesis-koa
[](https://travis-ci.org/confuser/exegesis-koa)
[](https://coveralls.io/github/confuser/exegesis-koa?branch=master)
[](https://snyk.io/test/github/confuser/exegesis-koa?targetFile=package.json)
> ## *exegesis*
>
> *n.* An explanation or critical interpretation of a text, especially an
> API definition document.
>
> -- No dictionary ever
This library implements a Koa middleware for
[OpenAPI 3.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#requestBodyObject).
##
```
npm install exegesis-koa
```
## Tutorial
Check out the tutorial [here](https://github.com/exegesis-js/exegesis/blob/master/docs/Tutorial.md).
## Usage
```js
const Koa = require('koa')
const path = require('path')
const exegesisKoa = require('exegesis-koa')
async function createServer() {
// See https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md
const options = {
controllers: path.resolve(__dirname, './controllers')
}
const exegesisMiddleware = exegesisKoa(path.resolve(__dirname, './openapi.yaml'), options)
const app = new Koa()
// If you have any body parsers, this should go before them.
app.use(async (ctx, next) => {
try {
await next()
} catch (err) {
ctx.status = 500
ctx.body = `Internal error: ${err.message}`
}
})
app.use(exegesisMiddleware)
app.use(async (ctx) => {
if (ctx.status === 404) {
ctx.status = 404
}
})
app.listen()
}
```
Calling `exegesiskoa(openApiFile, options)` will return a Promise
which resolves to a koa middleware.
`openApiFile` is either a path to your openapi.yaml or openapi.json file,
or it can be a JSON object with the contents of your OpenAPI document. This
should have the [`x-exegesis-controller`](https://github.com/exegesis-js/exegesis/blob/master/docs/OAS3%20Specification%20Extensions.md)
extension defined on any paths you want to be able to access.
`options` can be [anything you can pass to exegesis](https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md). At a
minimum, you'll probably want to provide `options.controllers`, a path to where
your [controller modules](https://github.com/exegesis-js/exegesis/blob/master/docs/Exegesis%20Controllers.md)
can be found. If you have any security requirements defined, you'll also
want to pass in some [authenticators](https://github.com/exegesis-js/exegesis/blob/master/docs/OAS3%20Security.md).
To enable response validation, you'll want to provide a validation callback
function via [`onResponseValidationError()`](https://github.com/exegesis-js/exegesis/blob/master/docs/Options.md#onresponsevalidationerror).
Exegesis's functionality can also be extended using [plugins](https://github.com/exegesis-js/exegesis/tree/master/docs),
which run on every request. Plugins let you add functionality like
[role base authorization](https://github.com/exegesis-js/exegesis-plugin-roles),
or CORS.