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

@quinck/fastify-openapi-glue

v4.1.5

Published

generate a fastify configuration from an openapi specification

Downloads

9

Readme

Fastify OpenApi Glue

CI status Coverage Status Language grade: JavaScript NPM version npm

A plugin for fastify to autogenerate a configuration based on a OpenApi(v2/v3) specification.

It aims at facilitating "design first" API development i.e. you write or obtain an API specification and use that to generate code. Given an OpenApi specification Fastify-openapi-glue handles the fastify configuration of routes and schemas etc. You can also generate your own project from a OpenApi specification.

Upgrading

If you are upgrading from a previous major version of fastify-openapi-glue then please checkout UPGRADING.md.

Install

npm i fastify-openapi-glue --save

Plugin

Usage

Add the plugin to your project with register and pass it some basic options and you are done !

import openapiGlue from "fastify-openapi-glue";
import { Service } from "./service.js";
import { Security } from "./security.js";

const options = {
  specification: `${currentDir}/petstore-openapi.v3.json`,
  service: new Service(),
  securityHandlers: new Security(),
  prefix: "v1",
};


fastify.register(openapiGlue, options);

All schema and routes will be taken from the OpenApi specification listed in the options. No need to specify them in your code.

Options

  • specification: this can be a JSON object, or the name of a JSON or YAML file containing a valid OpenApi(v2/v3) file
  • service: this can be a javascript object or class instance
  • securityHandlers: this can be a javascript object or class instance. See the securityHandlers documentation for more details.
  • prefix: this is a string that can be used to prefix the routes, it is passed verbatim to fastify. E.g. if the path to your operation is specified as "/operation" then a prefix of "v1" will make it available at "/v1/operation". This setting overrules any "basePath" setting in a v2 specification. See the servers documentation for more details on using prefix with a v3 specification.
  • operationResolver: a custom operation resolver function, (operationId, method, openapiPath) => handler where method is the uppercase HTTP method (e.g. "GET") and openapiPath is the path taken from the specification without prefix (e.g. "/operation"). Mutually exclusive with service.

specification and service are mandatory, securityHandlers and prefix are optional. See the examples section for a demo.

Please be aware that this will refer to your service object or your securityHandler object and not to Fastify as explained in the bindings documentation

OpenAPI extensions

The OpenAPI specification supports extending an API spec to describe extra functionality that isn't covered by the official specification. Extensions start with x- (e.g., x-myapp-logo) and can contain a primitive, an array, an object, or null.

The following extensions are provided by the plugin:

  • x-fastify-config (object): any properties will be added to the routeOptions.config / context.config property of the Fastify route.

    For example, if you wanted to use the fastify-raw-body plugin to compute a checksum of the request body, you could add the following extension to your OpenAPI spec to signal the plugin to specially handle this route:

    paths:
      /webhooks:
        post:
          operationId: processWebhook
          x-fastify-config:
            rawBody: true
          responses:
            204:
              description: Webhook processed successfully

You can also set custom OpenAPI extensions (e.g., x-myapp-foo) for use within your app's implementation. These properties are passed through unmodified to the Fastify route on {req,reply}.context. Extensions specified on a schema are also accessible (e.g., context.schema.body or context.schema.responses[<statusCode>]).

Generator

To make life even more easy there is the openapi-glue cli. The openapi-glue cli takes a valid OpenApi (v2/v3) file (JSON or YAML) and generates a project including a fastify plugin that you can use on any fastify server, a stub of the service class and a skeleton of a test harness to test the plugin.

Usage

  openapi-glue [options] <OpenApi specification>

or if you don't have openapi-glue installed:

  npx github:seriousme/fastify-openapi-glue <OpenApi specification>

This will generate a project based on the provided OpenApi specification. Any existing files in the project folder will be overwritten! See the generator examples section for a demo.

Options


  -p <name>                   The name of the project to generate
  --projectName=<name>        [default: generatedProject]

  -b <dir> --baseDir=<dir>    Directory to generate the project in.
                              This directory must already exist.
                              [default: "."]

The following options are only usefull for testing the openapi-glue plugin:
  -c --checksumOnly           Don't generate the project on disk but
                              return checksums only.
  -l --localPlugin            Use a local path to the plugin.

See the generator example section for a demo.

Examples

Clone this repository and run npm i

Plugin

Executing npm start will start fastify on localhost port 3000 with the routes extracted from the petstore example and the accompanying service definition

  • http://localhost:3000/v2/pet/24 will return a pet as specified in service.js
  • http://localhost:3000/v2/pet/myPet will return a fastify validation error:
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "params.petId should be integer"
}
  • http://localhost:3000/v2/pet/findByStatus?status=available&status=pending will return the following error:
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Operation findPetsByStatus not implemented"
}
  • http://localhost:3000/v2/pet/0 will return the following error:
{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message":"\"name\" is required!"
}

as the pet returned by service.js does not match the response schema.

Generator

The folder examples/generatedProject contains the result of running openapi-glue -l --baseDir=examples examples/petstore/petstore-swagger.v2.yaml. The generated code can be started using npm start in examples/generatedProject (you will need to run npm i in the generated folder first)

Notes

  • the plugin ignores information in a v3 specification under server/url as there could be multiple values here, use the prefix option if you need to prefix your routes. See the servers documentation for more details.
  • fastify only supports application/json and text/plain out of the box. The default charset is utf-8. If you need to support different content types, you can use the fastify addContentTypeParser API.
  • fastify will by default coerce types, e.g when you expect a number a string like "1" will also pass validation, this can be reconfigured, see Validation and Serialization.
  • fastify only supports one schema per route. So while the v3 standard allows for multiple content types per route, each with their own schema this is currently not going to work with fastify. Potential workarounds include a custom content type parser and merging schemas upfront using JSON schema oneOf.
  • the plugin aims to follow fastify and does not compensate for features that are possible according to the OpenApi specification but not possible in standard fastify (without plugins). This will keep the plugin lightweigth and maintainable.
  • if you have special needs on querystring handling (e.g. arrays, objects etc) then fastify supports a custom querystring parser. You might need to pass the AJV option coerceTypes: 'array' as an option to Fastify.

Contributing

  • contributions are always welcome.
  • if you plan on submitting new features then please create an issue first to discuss and avoid disappointments.
  • main development is done on the master branch therefore PRs to that branch are preferred.
  • please make sure you have run npm test before you submit a PR.

Fastify-swaggergen

Fastify-openapi-glue is the successor to the now deprecated fastify-swaggergen project. Main difference is that it:

  • aims to support OpenApi and not just Swagger V2 (hence the name change)
  • does not include fastify-swagger support anymore. If you need to show the swagger UI you can include it yourself. Removing the swagger UI clears up a number of dependencies.

License

Licensed under MIT