fastify-openapi-docs

A simple plugin for Fastify that generates OpenAPI spec automatically.

View on GitHub

Introduction

%s%s%s%s

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:

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

const server = require('fastify')()

server.register(require('fastify-openapi-docs'), {
  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: '^.+$',
      example: true
    }
  },
  required: ['id'],
  additionalProperties: false
})

server.addSchema({
  type: 'object',
  $id: '#response',
  description: 'The response payload',
  properties: {
    ok: {
      type: 'boolean',
      description: 'The operation response',
      example: true
    }
  },
  required: ['ok'],
  additionalProperties: false
})

server.route({
  method: 'POST',
  url: '/path',
  schema: {
    body: { $ref: '#request' },
    response: {
      200: { $ref: '#response' }
    }
  },
  config: {
    openapi: {
      description: 'Makes a request',
      summary: 'Main route',
      tags: ['service'],
      security: [{ jwtBearer: [] }]
    }
  },
  handler(_, reply) {
    reply.send({ ok: true })
  }
})

server.listen(3000)

Once started, the following routes will be available:

Note that $ref in the schemas will be resolved and replaced accordingly to OpenAPI spec.

Contributing to fastify-openapi-docs

Copyright

Copyright (C) 2021 and above Shogun (shogun@cowtech.it).

Licensed under the ISC license, which can be found at https://choosealicense.com/licenses/isc.

Your browser is obsolete. For the best browsing experience, update it for free by visiting BrowseHappy.
There is a shiny new version. Update now!
Made by a proud Italian!