Nighttime Peanut Migrations

    fastify-oas-forked
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.8 • Public • Published

    fastify-oas

    fastify-oas logo

    NPM Version Downloads Count Vunerabilities Count Build Status Coverage Status License

    OpenAPI 3.0+ (OAS3) documentation generator for Fastify. It uses the schemas you declare in your routes to generate an OpenAPI (swagger) compliant doc.

    This plugin based on fastify-swagger that generates swagger 2.0 docs.

    This plugin designed in such way to be compatible with it's predcessor and in most cases if you already use fastify-swagger you may just replace it with current plugin and it should work.

    ToC

    Fastify support

    • v0.X.X - v1.X.X - supports fastify v1.X.X
    • v2.X.X - will support fastify v2.X.X*
    Currently in Fastify v2.12.0 there's regression bug that breakes this exenstion for many users. So for now this extension doesn't support fastify 2.12.0. Cause it was cause by fastify minor change in order to preven issues this library will throw an error when you'll try to use it with that fastify version. In order to use it, you can either lock your fastify at 2.11.0 or fastify-oas at 2.5.0 (but there are no gaurantee that it will work correctly).

    Installation

    npm i fastify-oas --save

    Back to top

    Features and requirements

    • Supports OpenAPI 3+.
    • Supports fastify-swagger module configs.
    • Supports swagger 2.0 fastify schemas.
    • Supports fastify named schemas convertion to swaagger/openapi models.

    • Requires fastify >=1.9.0.
    • Node.js >=8.9.0.

    NOTE: If you need to generate fastify routes from your swagger document - please refer to plugins in See also like fastify-swaggergen or fastify-openapi-glue.

    Back to top

    Usage

    Add it to your project like regular fastify plugin. Use register method and pass it swagger options, then call the api constructor.

    const fastify = require('fastify');
    const oas = require('fastify-oas');
    const app = fastify();
    
    app.register(oas, {
      routePrefix: '/documentation',
      swagger: {
        info: {
          title: 'Test openapi',
          description: 'testing the fastify swagger api',
          version: '0.1.0',
        },
        externalDocs: {
          url: 'https://swagger.io',
          description: 'Find more info here',
        },
        consumes: ['application/json'],
        produces: ['application/json'],
      },
      exposeRoute: true
    });
    
    // put some routes and schemas
    
    app.ready(err => {
      if (err) throw err;
      app.oas();
    });

    Please note, the schema format for Fastify routes is JSONSchema and you may encounter some differences in the format for route spec vs. output OpenAPI spec.
    This plugin includes handling around a few of these differences.

    One such case is the example or examples keywords:

    fastify.route({
      method: 'POST',
      url: '/',
      schema: {
        body: {
          type: 'object',
          description: 'an object',
          examples: [
              {
                name: 'Object Sample',
                summary: 'an example',
                value: {a: 'payload'},
              }
          ],
          properties: {
            a: {type: 'string', description: 'your payload'}
          }
        }
      },
      handler: // ...
    })

    Which produces a spec similar to:

    {
      ... 
    
      "content": {
        "application/json": {
          "examples": {
            "Object Sample": {
              "summary": "an example",
              "value": {
                "a": "payload"
              }
            }
          },
          "schema": {
            "type": "object",
            "properties": {
              "a": {
                "type": "string",
                "description": "your payload"
              }
            }
          }
        }
      }
    }

    (in this case, the name property is extracted as the examples key)

    Back to top

    Docs

    See Docs for more details on the TypeScript types that you may use when working with OpenAPI spec.

    Plugin options

    parameter type description default
    routePrefix String Documentation endpoint /documentation
    exposeRoute Boolean Object** If true the plugin will expose the documentation with the following apis: /<routePrefix>, /<routePrefix>/json, /<routePrefix>/yaml
    addModels Boolean If true adds fastify schemas as openapi models* false
    openapi String Openapi version '3.0.0'
    yaml Boolean If true returns yaml instead of json false
    hideUntagged Boolean If true remove routes without tags in schema from resulting swagger file false
    swagger Object Swagger object except paths {}

    Note (*): Fastify-oas plugin gather all schemas, so you should ensure that all of them under current and nested scopes have unique names. Note (**): see Expose route options Back to top

    Additional schema options

    In order to remove some endpoints from Swagger/OpenAPI document you may add {hide: true} option to route schema.

    const fastify = require('fastify')()
    fastify.get('/some-secrete-route/:id', {
      schema: {
        hide: true,
        params: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              description: 'user id'
            }
          }
        },
        response: {
          201: {
            description: 'Successful response',
            type: 'object',
            properties: {
              hello: { type: 'string' }
            }
          }
        },
      }
    }, (req, reply) => {})

    Back to top

    OpenAPI

    Unlike regular OpenAPI spec you'll still need some options from swagger 2.0.

    const fastify = require('fastify');
    const oas = require('fastify-oas');
    const app = fastify();
    
    app.register(oas, {
      routePrefix: '/documentation',
      swagger: {
        info: {
          title: 'Test openapi',
          description: 'testing the fastify swagger api',
          version: '0.1.0',
        },
        externalDocs: {
          url: 'https://swagger.io',
          description: 'Find more info here',
        },
        consumes: ['application/json'], // app-wide default media-type
        produces: ['application/json'], // app-wide default media-type
        servers: [{
          url: 'http://api.example.com/v1',
          description: 'Optional server description, e.g. Main (production) server',
        }],
        components: {
          // see https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#componentsObject for more options
          securitySchemes: {
            BasicAuth: {
              type: 'http',
              scheme: 'basic',
            },
          },
        }, 
      },
    });

    Back to top

    Swagger 2.0

    This will not generate swagger 2.0 docs. It will generate openapi 3.0 docs, but from swagger 2.0 (and fastify-swagger) compatible configuration. It will allow easily migrate from fastify-swagger.

    The example below is taken from fastify-swagger repo to show the differences .

    const fastify = require('fastify')()
    
    // before: fastify.register(require('fastify-swagger'), {
    fastify.register(require('fastify-oas'), { // after
      routePrefix: '/documentation',
      swagger: {
        info: {
          title: 'Test swagger',
          description: 'testing the fastify swagger api',
          version: '0.1.0'
        },
        externalDocs: {
          url: 'https://swagger.io',
          description: 'Find more info here'
        },
        host: 'localhost',
        schemes: ['http'],
        consumes: ['application/json'],
        produces: ['application/json'],
        tags: [
          { name: 'user', description: 'User related end-points' },
          { name: 'code', description: 'Code related end-points' }
        ],
        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.oas()
    })

    Back to top

    UI

    Swagger UI is available via /<routePrefix>/index.html. By default it's /documentation/index.html.

    ReDoc UI is available via /<routePrefix>/docs.html. By default it's /documentation/docs.html.

    Back to top

    Development

    In order to start development run:

    npm i
    npm run prepare

    So that swagger-ui static folder will be generated for you.

    Back to top

    See also

    • fastify-swagger - swagger 2.0 docs generation plugin.
    • fastify-swaggergen - fastify routes generation from swagger 2.0 docs.
    • fastify-openapi-glue - fastify-swaggergen successor, generates fastify routes from swagger 2.0 and openapi 3.0 docs (just like this module, but in opposite direction).

    Back to top

    License

    Licensed under MIT.

    Back to top

    Install

    npm i fastify-oas-forked

    DownloadsWeekly Downloads

    181

    Version

    3.0.8

    License

    MIT

    Unpacked Size

    11.2 MB

    Total Files

    26

    Last publish

    Collaborators

    • chandelabhishek