Fastify swagger generator
A plugin for fastify to autogenerate a configuration based on a OpenApi(v2/v3) specification.
Fastify OpenApi Glue
This project has been replaced byInstall:
npm i fastify-swaggergen --save
Plugin
Usage
Add the plugin to your project with register
and pass it some basic options and you are done !
const swaggerGen = ; const options = swaggerSpec: `/petstore-swagger.v2.json` service: `/service.js` fastifySwagger: disabled: false ; fastify;
All schema and routes will be taken from the OpenApi specification listed in the options. No need to specify them in your code.
Options
swaggerSpec
: this can be a JSON object, or the name of a JSON or YAML file containing a valid OpenApi(v2/v3) fileservice
: 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.fastifySwagger
: an object containing the options for the fastify-swagger plugin. To avoid registering this plugin pass{ fastifySwagger: { disabled: true }}
Of these options swaggerSpec
and service
are mandatory, fastifySwagger
is optional.
See the examples section for a demo.
Generator
To make life even more easy there is the swaggergen
cli. The swaggergen
cli takes a valid OpenApi (v2/v3) file (JSON or YAML) and generates a project including a fastify flugin 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
swaggergen [options] <OpenApi specification>
or if you don't have swaggergen
installed:
npx github:seriousme/fastify-swaggergen <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 swaggergen 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/documentation will show the swagger UI, for comparison one could look at http://petstore.swagger.io/
- 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:
- http://localhost:3000/v2/pet/findByStatus?status=a&status=b will return the following error:
- http://localhost:3000/v2/pet/0 will return the following error:
as the pet returned by service.js does not match the response schema.
Generator
The folder examples/generatedProject contains the result of running swaggergen -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)
License
Licensed under MIT