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

    1.0.2 • Public • Published


    Version Dependencies Build Coverage

    A simple plugin for Fastify that generates OpenAPI spec automatically.


    Just run:

    npm install fastify-openapi-docs --save


    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 set true, 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}.


    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: '',
            email: ''
          license: {
            name: 'ISC',
            url: ``
          version: '1.0.0'
        servers: [
          { url: '', description: 'Production Server' },
          { url: '', description: 'Development Server' }
        tags: [{ name: 'service', description: 'Service' }],
        components: {
          securitySchemes: {
            jwtBearer: {
              type: 'http',
              scheme: 'bearer',
              bearerFormat: 'JWT'
      type: 'object',
      $id: '#request',
      description: 'The request payload',
      properties: {
        id: {
          type: 'string',
          description: 'The operation id',
          pattern: '^.+$',
          example: true
      required: ['id'],
      additionalProperties: false
      type: 'object',
      $id: '#response',
      description: 'The response payload',
      properties: {
        ok: {
          type: 'boolean',
          description: 'The operation response',
          example: true
      required: ['ok'],
      additionalProperties: false
      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 })

    Once started, the following routes will be available:

    • http://localhost:3000/docs/openapi.yaml
    • http://localhost:3000/docs/openapi.json
    • http://localhost:3000/docs (OpenAPI UI)

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

    ESM Only

    This package only supports to be directly imported in a ESM context.

    For informations on how to use it in a CommonJS context, please check this page.

    Contributing to fastify-openapi-docs

    • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
    • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
    • Fork the project.
    • Start a feature/bugfix branch.
    • Commit and push until you are happy with your contribution.
    • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.


    Copyright (C) 2021 and above Shogun (

    Licensed under the ISC license, which can be found at


    npm i fastify-openapi-docs

    DownloadsWeekly Downloads






    Unpacked Size

    17.1 kB

    Total Files


    Last publish


    • shogun_panda