Have ideas to improve npm?Join in the discussion! »

fastify-openapi-glueTypeScript icon, indicating that this package has built-in type declarations

2.3.1 • Public • Published

Fastify OpenApi Glue

CI status

NPM version npm

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

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 !

const openapiGlue = require("fastify-openapi-glue");

const options = {
  specification: `${__dirname}/petstore-openapi.v3.json`,
  service: `${__dirname}/service.js`,
  securityHandlers: `${__dirname}/security.js`,
  prefix: "v1",
  noAdditional: true,
  ajvOptions: {
    formats: {
      "custom-format": /\d{2}-\d{4}/
    }
  }
};


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, or the name of a javascript file containing such an object. If the import of the file results in a function instead of an object then the function will be executed during import.
  • securityHandlers: this can be a javascript object or class, or the name of a javascript file containing such an object. If the import of the file results in a function instead of an object then the function will be executed during import. 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.
  • noAdditional: by default Fastify will silently ignore additional properties in a message. Setting noAdditional to true will change this behaviour and will make Fastify return a HTTP error 400 when additional properties are present. Default value for this option is false.
  • ajvOptions: Pass additional options to AJV (see https://ajv.js.org/#options)

specification and service are mandatory, securityHandlers, prefix and noAdditional are optional.

See the examples section for a demo.

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

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

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

Install

npm i fastify-openapi-glue

DownloadsWeekly Downloads

1,881

Version

2.3.1

License

MIT

Unpacked Size

288 kB

Total Files

61

Last publish

Collaborators

  • avatar