README
fastify-openapi-docs
A simple plugin for Fastify that generates OpenAPI spec automatically.
http://sw.cowtech.it/fastify-openapi-docs
Installation
Just run:
npm install fastify-openapi-docs --save
Usage
Register as a plugin as early as possible (in order to track all routes), optional providing any of the following options:
openapi
: The OpenAPI document header.prefix
: Where to serve the OpenAPI files. The default value is/docs/
.skipUI
: If settrue
, the the OpenAPI / Swagger UI will not be served.
Routes should contain a openapi
object inside the config
with all desired OpenAPI annotations.
Non JSON responses can be generated by setting the $raw
key in the response schema to the appropriate MIME type.
Empty responses can be generated by setting the $empty
key in the response schema to true
.
Routes can be omitted from spec by the list by setting hide
option to true
inside their config
.
Once the server is started, it will serve the OpenAPI specification on both /{prefix}/openapi.json
and /{prefix}/openapi.yaml
.
If the UI is enabled, it will be reachable at /${prefix}
.
Example
import fastify from 'fastify'
import fastifyOpenapiDocs from 'fastify-openapi-docs'
const server = fastify()
server.register(fastifyOpenapiDocs, {
openapi: {
// All these fields are optional, but they should be provided to satisfy OpenAPI specification.
openapi: '3.0.3',
info: {
title: 'Title',
description: 'Description',
contact: {
name: 'Shogun',
url: 'https://cowtech.it',
email: 'shogun@cowtech.it'
},
license: {
name: 'ISC',
url: `https://choosealicense.com/licenses/isc/`
},
version: '1.0.0'
},
servers: [
{ url: 'https://example.com', description: 'Production Server' },
{ url: 'https://dev.example.com', description: 'Development Server' }
],
tags: [{ name: 'service', description: 'Service' }],
components: {
securitySchemes: {
jwtBearer: {
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT'
}
}
}
}
})
server.addSchema({
type: 'object',
$id: '#request',
description: 'The request payload',
properties: {
id: {
type: 'string',
description: 'The operation id',
pattern: '^.+