{"id":13576029,"url":"https://github.com/seriousme/fastify-openapi-glue","last_synced_at":"2025-05-15T04:04:16.426Z","repository":{"id":37493191,"uuid":"139273011","full_name":"seriousme/fastify-openapi-glue","owner":"seriousme","description":"A plugin for the Fastify  webserver to autogenerate a Fastify configuration based on a OpenApi(v2/v3) specification.","archived":false,"fork":false,"pushed_at":"2025-05-14T17:28:45.000Z","size":3326,"stargazers_count":220,"open_issues_count":1,"forks_count":34,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-14T18:42:35.807Z","etag":null,"topics":["apis","design-first","fastify","fastify-plugin","javascript","openapi","openapi-codegen","openapi-specification","openapi3","openapi3-1","swagger"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/seriousme.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/securityHandlers.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-30T19:02:58.000Z","updated_at":"2025-05-14T17:28:41.000Z","dependencies_parsed_at":"2023-09-28T01:57:47.534Z","dependency_job_id":"f94b8fe3-d03f-43ce-a11e-9b4c9ef9fc28","html_url":"https://github.com/seriousme/fastify-openapi-glue","commit_stats":{"total_commits":949,"total_committers":20,"mean_commits":47.45,"dds":0.530031612223393,"last_synced_commit":"3ab9d07e1fc9c255de7e9a47f6dc6a197919db45"},"previous_names":[],"tags_count":82,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Ffastify-openapi-glue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Ffastify-openapi-glue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Ffastify-openapi-glue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/seriousme%2Ffastify-openapi-glue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/seriousme","download_url":"https://codeload.github.com/seriousme/fastify-openapi-glue/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254270640,"owners_count":22042858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apis","design-first","fastify","fastify-plugin","javascript","openapi","openapi-codegen","openapi-specification","openapi3","openapi3-1","swagger"],"created_at":"2024-08-01T15:01:06.427Z","updated_at":"2025-05-15T04:04:16.388Z","avatar_url":"https://github.com/seriousme.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","javascript"],"sub_categories":[],"readme":"# Fastify OpenApi Glue\n[![CI status](https://github.com/seriousme/fastify-openapi-glue/workflows/Node.js%20CI/badge.svg)](https://github.com/seriousme/fastify-openapi-glue/actions?query=workflow%3A%22Node.js+CI%22)\n[![Coverage Status](https://coveralls.io/repos/github/seriousme/fastify-openapi-glue/badge.svg?branch=master)](https://coveralls.io/github/seriousme/fastify-openapi-glue?branch=master)\n[![NPM version](https://img.shields.io/npm/v/fastify-openapi-glue.svg)](https://www.npmjs.com/package/fastify-openapi-glue)\n![npm](https://img.shields.io/npm/dm/fastify-openapi-glue)\n\n\n\nA plugin for [fastify](https://fastify.dev) to autogenerate a configuration based on a [OpenApi](https://www.openapis.org/)(v2/v3) specification.\n\nIt aims at facilitating [\"design first\" API development](https://swagger.io/blog/api-design/design-first-or-code-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](#generator) your own project from a OpenApi specification.\n\n\u003ca name=\"upgrading\"\u003e\u003c/a\u003e\n## Upgrading\n\nIf you are upgrading from a previous major version of `fastify-openapi-glue` then please check out [UPGRADING.md](UPGRADING.md).\n\n\u003ca name=\"install\"\u003e\u003c/a\u003e\n## Install \n```\nnpm i fastify-openapi-glue --save\n```\n\u003ca name=\"plugin\"\u003e\u003c/a\u003e\n## Plugin\n\u003ca name=\"pluginUsage\"\u003e\u003c/a\u003e\n### Usage\n\nAdd the plugin to your project with `register` and pass it some basic options and you are done !\n```javascript\nimport openapiGlue from \"fastify-openapi-glue\";\nimport { Service } from \"./service.js\";\nimport { Security } from \"./security.js\";\n\nconst options = {\n  specification: `${currentDir}/petstore-openapi.v3.json`,\n  serviceHandlers: new Service(),\n  securityHandlers: new Security(),\n  prefix: \"v1\",\n};\n\n\nfastify.register(openapiGlue, options);\n```\n\nAll schema and routes will be taken from the OpenApi specification listed in the options. No need to specify them in your code. \n\u003ca name=\"pluginOptions\"\u003e\u003c/a\u003e\n### Options\n  - `specification`: this can be a JSON object, or the name of a JSON or YAML file containing a valid OpenApi(v2/v3) file \n  - `serviceHandlers`: this can be a javascript object or class instance. See the [serviceHandlers documentation](docs/serviceHandlers.md) for more details.\n  - `securityHandlers`: this can be a javascript object or class instance. See the [securityHandlers documentation](docs/securityHandlers.md) for more details.\n  - `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](docs/servers.md) for more details on using prefix with a v3 specification.\n - `operationResolver`: a custom operation resolver function, `(operationId, method, openapiPath) =\u003e handler | routeOptions` 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 `serviceHandlers`. See the [operationResolver documentation](docs/operationResolver.md) for more details.\n - `addEmptySchema`: a boolean that allows empty bodies schemas to be passed through. This might be useful for status codes like 204 or 304. Default is `false`.\n\n`specification` and either `serviceHandlers` or `operationResolver` are mandatory, `securityHandlers` and `prefix` are optional.\nSee the [examples](#examples) section for a demo.\n\nPlease be aware that `this` will refer to your serviceHandlers object or your securityHandler object and not to Fastify as explained in the [bindings documentation](docs/bindings.md)\n\n\u003ca name=\"pluginApiExtensions\"\u003e\u003c/a\u003e\n### OpenAPI extensions\nThe OpenAPI specification supports [extending an API spec](https://spec.openapis.org/oas/latest.html#specification-extensions) 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`.\n\nThe following extensions are provided by the plugin:\n- `x-fastify-config` (object): any properties will be added to the `routeOptions.config` property of the Fastify route.\n\n  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:\n\n  ```yaml\n  paths:\n    /webhooks:\n      post:\n        operationId: processWebhook\n        x-fastify-config:\n          rawBody: true\n        responses:\n          204:\n            description: Webhook processed successfully\n  ```\n\n- `x-no-fastify-config` (true): this will ignore this specific route as if it was not present in your OpenAPI specification:\n\n```yaml\n  paths:\n    /webhooks:\n      post:\n        operationId: processWebhook\n        x-no-fastify-config: true\n        responses:\n          204:\n            description: Webhook processed successfully\n  ```\n\nYou 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[\u003cstatusCode\u003e]`).\n\n\u003ca name=\"generator\"\u003e\u003c/a\u003e\n## Generator\n\nTo 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. \n\n\u003ca name=\"generatorUsage\"\u003e\u003c/a\u003e\n### Usage\n```\n  openapi-glue [options] \u003cOpenApi specification\u003e\n```\nor if you don't have `openapi-glue` installed:\n```\n  npx github:seriousme/fastify-openapi-glue \u003cOpenApi specification\u003e\n```\nThis will generate a project based on the provided OpenApi specification.\nAny existing files in the project folder will be overwritten!\nSee the [generator examples](#examples) section for a demo.\n\u003ca name=\"generatorOptions\"\u003e\u003c/a\u003e\n### Options\n```\n\n  -p \u003cname\u003e                   The name of the project to generate\n  --projectName=\u003cname\u003e        [default: generated-javascript-project]\n\n  -b \u003cdir\u003e --baseDir=\u003cdir\u003e    Directory to generate the project in.\n                              This directory must already exist.\n                              [default: \".\"]\n\nThe following options are only usefull for testing the openapi-glue plugin:\n  -c --checksumOnly           Don't generate the project on disk but\n                              return checksums only.\n  -l --localPlugin            Use a local path to the plugin.\n```\nSee the [generator example](#generatorExamples) section for a demo.\n\n\n\u003ca name=\"examples\"\u003e\u003c/a\u003e\n## Examples\nClone this repository and run `npm i` \n\n\u003ca name=\"pluginExamples\"\u003e\u003c/a\u003e\n### Plugin\nExecuting `npm start` will start fastify on localhost port 3000 with the\nroutes extracted from the [petstore example](examples/petstore/petstore-openapi.v3.json) and the [accompanying serviceHandlers definition](examples/petstore/service.js)\n\n* http://localhost:3000/v2/pet/24 will return a pet as specified in service.js\n* http://localhost:3000/v2/pet/myPet will return a fastify validation error:\n\n```json\n{\n  \"statusCode\": 400,\n  \"error\": \"Bad Request\",\n  \"message\": \"params.petId should be integer\"\n}\n```\n\n* http://localhost:3000/v2/pet/findByStatus?status=available\u0026status=pending will return\n  the following error:\n\n```json\n{\n  \"statusCode\": 500,\n  \"error\": \"Internal Server Error\",\n  \"message\": \"Operation findPetsByStatus not implemented\"\n}\n```\n\n* http://localhost:3000/v2/pet/0 will return the following error:\n\n```json\n{\n  \"statusCode\": 500,\n  \"error\": \"Internal Server Error\",\n  \"message\":\"\\\"name\\\" is required!\"\n}\n```\n\nas the pet returned by service.js does not match the response schema.\n\n\u003ca name=\"generatorExamples\"\u003e\u003c/a\u003e\n### Generator\nThe folder [examples/generated-javascript-project](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)\n\u003ca name=\"Notes\"\u003e\u003c/a\u003e\n## Notes\n- the plugin ignores information in a v3 specification under `server/url` as there could be multiple values here, use the `prefix` [option](#pluginOptions) if you need to prefix your routes. See the [servers documentation](docs/servers.md) for more details.\n- 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.\n- 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](https://fastify.dev/docs/latest/Reference/Validation-and-Serialization/).\n- 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. E.g. Fastify does not support cookie validation, while OpenApi v3 does.\n- in some cases however, the plugin may be able to provide you with data which could be used to enhance OpenApi support within your own Fastify application. Here is one possible way to perform [cookie validation](docs/cookieValidationHowTo.md)  yourself.\n- if you have special needs on querystring handling (e.g. arrays, objects etc) then fastify supports a [custom querystring parser](https://fastify.dev/docs/latest/Reference/Server/#querystringparser). You might need to pass the AJV option `coerceTypes: 'array'` as an option to Fastify.\n- the plugin is an ECMAscript Module (aka ESM). If you are using Typescript then make sure that you have read: https://www.typescriptlang.org/docs/handbook/esm-node.html to avoid any confusion.\n- If you want to use a specification that consists of multiple files then please check out the page on [subschemas](docs/subSchemas.md) \n- Fastify uses AJV strict mode in validating schemas. If you get an error like `....due to error strict mode: unknown keyword: \"...\"` then please check out the page on [AJV strict mode](docs/AJVstrictMode.md) \n- Fastify does not support `multipart/form-data` out of the box. If you want to use it then have a look at: [@fastify/multipart](https://github.com/fastify/fastify-multipart).\n- Fastify uses AJV with JSON schema draft-07 out of the box. If you want to use JSON schema draft-2020-12 features in your OpenApi 3.1+ schema then have a look at [using JSONschema 2020](docs/schema2020.md) \n\n\u003ca name=\"Contributing\"\u003e\u003c/a\u003e\n## Contributing\n- contributions are always welcome. \n- if you plan on submitting new features then please create an issue first to discuss and avoid disappointments.\n- main development is done on the master branch therefore PRs to that branch are preferred.\n- please make sure you have run `npm test` before you submit a PR.\n\u003ca name=\"Fastify-swaggergen\"\u003e\u003c/a\u003e\n## Fastify-swaggergen\nFastify-openapi-glue is the successor to the now deprecated [fastify-swaggergen](https://github.com/seriousme/fastify-swaggergen) project.\nMain difference is that it: \n- aims to support OpenApi and not just Swagger V2 (hence the name change)\n- 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.\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n# License\nLicensed under [MIT](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseriousme%2Ffastify-openapi-glue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fseriousme%2Ffastify-openapi-glue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fseriousme%2Ffastify-openapi-glue/lists"}