Express OpenAPI


A middleware for generating and validating OpenAPI documentation from an Express app.

This middleware will look at the routes defined in your app and fill in as much as it can about them
into an OpenAPI document. Optionally you can also flesh out request and response schemas, parameters, and
other parts of your api spec with path specific middleware. The final document will be exposed as json
served by the main middleware (along with component specific documents).

Philosophy

It is common in the OpenAPI community to talk about generating code from documentation. There is value
in this approach, as often it is easier for devs to let someone else make the implementation decisions
for them. For me, I feel the opposite. I am an engineer whose job it is to make good decisions about
writing quality code. I want control of my application, and I want to write code. With this module I can
both write great code, as well as have great documentation!

Installation

``
$ npm install --save @wesleytodd/openapi
`

Usage

`javascript
const openapi = require('@wesleytodd/openapi')
const app = require('express')()

const oapi = openapi({
openapi: '3.0.0',
info: {
title: 'Express Application',
description: 'Generated docs from an Express api',
version: '1.0.0',
}
})

// This will serve the generated json document(s)
// (as well as the swagger-ui if configured)
app.use(oapi)

// To add path specific schema you can use the .path middleware
app.get('/', oapi.path({
responses: {
200: {
description: 'Successful response',
content: {
'application/json': {
schema: {
type: 'object',
properties: {
hello: { type: 'string' }
}
}
}
}
}
}
}), (req, res) => {
res.json({
hello: 'world'
})
})

app.listen(8080)
`

In the above example you can see the output of the OpenAPI spec by requesting /openapi.json.

`shell
$ curl -s http://localhost:8080/openapi.json | jq .
{
"openapi": "3.0.0",
"info": {
"title": "Express Application",
"version": "1.0.0",
"description": "Generated docs from an Express api"
},
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"hello": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
`

Api Docs

$3

Creates an instance of the documentation middleware. The function that is returned
is a middleware function decorated with helper methods for setting up the api documentation.

Options:

- route : A route for which the documentation will be served at
- document