Home

Awesome

Fastify OpenApi Glue

CI status Coverage Status 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 validation schemas etc. You can also generate your own project from a OpenApi specification.

<a name="upgrading"></a>

Upgrading

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

<a name="install"></a>

Install

npm i fastify-openapi-glue --save

<a name="plugin"></a>

Plugin

<a name="pluginUsage"></a>

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`,
  serviceHandlers: 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. <a name="pluginOptions"></a>

Options

specification and either serviceHandlers or operationResolver are mandatory, securityHandlers and prefix are optional. See the examples section for a demo.

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

<a name="pluginApiExtensions"></a>

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:

  paths:
    /webhooks:
      post:
        operationId: processWebhook
        x-no-fastify-config: 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}.routeOptions.config. Extensions specified on a schema are also accessible (e.g., routeOptions.schema.body or routeOptions.schema.responses[<statusCode>]).

<a name="generator"></a>

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 serviceHandlers class and a skeleton of a test harness to test the plugin.

<a name="generatorUsage"></a>

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. <a name="generatorOptions"></a>

Options


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

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

<a name="examples"></a>

Examples

Clone this repository and run npm i

<a name="pluginExamples"></a>

Plugin

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

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "params.petId should be integer"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Operation findPetsByStatus not implemented"
}

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message":"\"name\" is required!"
}

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

<a name="generatorExamples"></a>

Generator

The folder examples/generated-javascript-project 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/generated-javascript-project (you will need to run npm i in the generated folder first) <a name="Notes"></a>

Notes

Contributing

Fastify-swaggergen

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

License

Licensed under MIT