npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

fastify-openapi-docs

v3.0.4

Published

A simple plugin for Fastify that generates OpenAPI spec automatically.

Downloads

1,552

Readme

fastify-openapi-docs

Version Dependencies Build Coverage

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 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.

When using $raw or $empty, always remember to provide the type by setting it to string or object:

/* ... */
response: {
  200: {
    type: 'string',
    $raw: 'text/html'
  }
}
/* ... */

Routes can be omitted from spec by the list by setting hide option to true inside their config.

HEAD routes automatically created by fastify when declaring GET routes can be omitted from spec by the list by setting hideHead option to true inside their config.

Routes can accept MIME types other than application/json by providing it in the bodyMime option 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()

/*
Since fastify-openapi-docs uses an onRoute hook, you have to either:

* use `await register...`
* wrap you routes definitions in a plugin

See: https://www.fastify.io/docs/latest/Guides/Migration-Guide-V4/#synchronous-route-definitions
*/
await 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: '[email protected]'
      },
      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: '^.+$'
    }
  },
  required: ['id'],
  additionalProperties: false
})

server.addSchema({
  type: 'object',
  $id: 'response',
  description: 'The response payload',
  properties: {
    ok: {
      type: 'boolean',
      description: 'The operation response'
    }
  },
  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({ port: 3000 })

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

Copyright (C) 2021 and above Shogun ([email protected]).

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