Skip to content

cortopy/fastify-swagger

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

80 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

fastify-swagger

js-standard-style Build Status

Swagger documentation generator for Fastify.
It uses the schemas you declare in your routes to generate a swagger compliant doc.

Install

npm i fastify-swagger --save

Usage

Add it to your project with register and pass it some basic options, then call the swagger api and you are done!

const fastify = require('fastify')()

fastify.register(require('fastify-swagger'), {
  swagger: {
    info: {
      title: 'Test swagger',
      description: 'testing the fastify swagger api',
      version: '0.1.0'
    },
    host: 'localhost',
    schemes: ['http'],
    consumes: ['application/json'],
    produces: ['application/json'],
    securityDefinitions: {
      apiKey: {
        type: 'apiKey',
        name: 'apiKey',
        in: 'header'
      }
    }
  }
})

fastify.put('/some-route/:id', {
  schema: {
    description: 'post some data',
    tags: ['user', 'code'],
    summary: 'qwerty',
    params: {
      type: 'object',
      properties: {
        id: {
          type: 'string',
          description: 'user id'
        }
      }
    },
    body: {
      type: 'object',
      properties: {
        hello: { type: 'string' },
        obj: {
          type: 'object',
          properties: {
            some: { type: 'string' }
          }
        }
      }
    },
    response: {
      201: {
        description: 'Successful response',
        type: 'object',
        properties: {
          hello: { type: 'string' }
        }
      }
    },
    security: [
      {
        "api_key": []
      }
    ]
  }
}, (req, reply) => {})

fastify.ready(err => {
  if (err) throw err
  fastify.swagger()
})

API

register options

{
  swagger: {
    info: {
      title: String,
      description: String,
      version: String
    },
    host: String,
    schemes: [ String ],
    consumes: [ String ],
    produces: [ String ],
    securityDefinitions: Object
  }
}

All the above parameters are optional.
You can use all the properties of the swagger specification, if you find anything missing, please open an issue or a pr!

swagger options

Calling fastify.swagger will return to you a JSON object representing your api, if you pass { yaml: true } to fastify.swagger, it will return you a yaml string.

If you pass { exposeRoute: true } the plugin will expose the documentation with the following apis:

url description
'/documentation/json' the json object representing the api
'/documentation/yaml' the yaml object representing the api
'/documentation' the swagger ui

Hide a route

Sometimes you may need to hide a certain route from the documentation, just pass { hide: true } to the schema object inside the route declaration.

Security

Global security definitions and route level security provide documentation only. It does not implement authentication nor route security for you. Once your authentication is implemented, along with your defined security, users will be able to successfully authenticate and interact with your API using the user interfaces of the documentation.

Acknowledgements

This project is kindly sponsored by:

License

Licensed under MIT.

About

Swagger documentation generator for Fastify

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 82.3%
  • HTML 17.7%