{"id":21385324,"url":"https://github.com/touchifyapp/fastify-oapi","last_synced_at":"2025-03-16T11:44:35.358Z","repository":{"id":42867401,"uuid":"258921570","full_name":"touchifyapp/fastify-oapi","owner":"touchifyapp","description":"Fastify plugin to make your fastify server fully compliant with Open API v3","archived":false,"fork":false,"pushed_at":"2023-10-15T15:37:04.000Z","size":808,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-11T16:41:59.851Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/touchifyapp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-26T02:34:04.000Z","updated_at":"2023-04-10T20:49:02.000Z","dependencies_parsed_at":"2024-10-23T08:55:25.788Z","dependency_job_id":"fa673200-9b12-44d3-bf2f-d83af78b4fd4","html_url":"https://github.com/touchifyapp/fastify-oapi","commit_stats":{"total_commits":66,"total_committers":4,"mean_commits":16.5,"dds":"0.19696969696969702","last_synced_commit":"63376c6eea32855c5fe1acdee236b67ac3770e6f"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touchifyapp%2Ffastify-oapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touchifyapp%2Ffastify-oapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touchifyapp%2Ffastify-oapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/touchifyapp%2Ffastify-oapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/touchifyapp","download_url":"https://codeload.github.com/touchifyapp/fastify-oapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243864626,"owners_count":20360355,"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":[],"created_at":"2024-11-22T11:46:48.737Z","updated_at":"2025-03-16T11:44:35.309Z","avatar_url":"https://github.com/touchifyapp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fastify-oapi\n\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](http://opensource.org/licenses/MIT)\n[![NPM version](https://img.shields.io/npm/v/fastify-oapi.svg?style=flat-square)](https://npmjs.org/package/fastify-oapi)\n[![NPM download](https://img.shields.io/npm/dm/fastify-oapi.svg?style=flat-square)](https://npmjs.org/package/fastify-oapi)\n[![Unit Tests](https://github.com/touchifyapp/fastify-oapi/workflows/Unit%20Tests/badge.svg)](https://github.com/touchifyapp/fastify-oapi/actions?query=workflow%3A%22Unit+Tests%22)\n[![Test Coverage](https://coveralls.io/repos/github/touchifyapp/fastify-oapi/badge.svg)](https://coveralls.io/github/touchifyapp/fastify-oapi)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\n## Installation\n\n```bash\nnpm install fastify-oapi\n```\n\n## Compatibility matrix\n\n| `fastify-oapi` version | `fastify` version |\n|------------------------|-------------------|\n| `v1.x`                 | `v3.x`            |\n| `v2.x`                 | `v4.x` *          |\n\n_* Fastify v4 uses Ajv v8 per default. So it's not possible to use json schema draft-04 to fully align to OpenAPI v3.0 specification._\n\n## Simple Usage\n\n```typescript\nimport * as Fastify from \"fastify\";\nimport fastifyOpenApi, { getAjvOptions } from \"fastify-oapi\";\n\nimport * as controller from \"./controller\";\n\nconst specification = __dirname + \"/openapi.yml\"\n\n// Extend Fastify Ajv options to be fully Open API v3 compliant\nfastify = Fastify({\n    ajv: getAjvOptions()\n});\n\n// Configure the plugin\nfastify.register(fastifyOpenApi, {\n    specification,\n    controller,\n});\n\nawait fastify.listen(3000);\n```\n\n## Options\n\n- `specification`: A valid Open API v3 specification. It can be provided as a path, an URL or a JavaScript object.\n- `resolution`: Specify how to resolve controllers. See [Controller Resolution](#Controller-Resolution).\n- `controller`: When using `unique` resolution mode, this value is used to resolve to a controller for the API. See [Controller Resolution](#Controller-Resolution).\n- `controllersDir`: When using `per-route` or `per-operation` resolution mode, this value is used to determine where controllers are located. See [Controller Resolution](#Controller-Resolution).\n- `resolutionConfig`: When using `manual` resolution mode, this value is used to configure how routes are mapped to controllers. See [Controller Resolution](#Controller-Resolution).\n- `prefix`: Routes URL prefix *(eg: `/route` with `/v1` prefix create a `/v1/route` route)*.\n\n## Configure Fastify Ajv instance\n\nTo allow some openapi extensions `fastify-oapi` provides an `ajv` plugin. To enable the plugin, `fastify-oapi` provides the `getAjvOptions()` help.\n\n```typescript\nimport * as Fastify from \"fastify\";\nimport { getAjvOptions } from \"fastify-oapi\";\n\n// Add ajv plugin with no options\nfastify = Fastify({\n    ajv: getAjvOptions()\n});\n\n// Extends Ajv custom options\nfastify = Fastify({\n    ajv: getAjvOptions(\n        { removeAdditional: false }\n    )\n});\n\n// Add other Ajv plugins\nfastify = Fastify({\n    ajv: getAjvOptions(\n        { removeAdditional: false },\n        [\n            [otherPlugin, otherPluginOptions]\n        ]\n    )\n});\n\n## Controller Resolution\n\n`fastify-oapi` can resolve controllers in multiple ways. It can be configured via the option `resolution`. This option accept the following values: `per-route`, `per-operation`, `unique` or `manual`.\n\n#### per-route\n\nThe mode `per-route` is an automatic resolution mode. It looks for controllers based on the route URL. **It requires the `controllersDir` option.**\n\nExamples:\n- `/pets` routes to `pets.controller.js` in `controllersDir`.\n- `/pets/:petId` routes to `pets.controller.js` in `controllersDir`.\n- `/pets/getByStatus` routes to `pets.controller.js` in `controllersDir`.\n- `/` routes to `root.controller.js` in `controllersDir`.\n- `/:rootId` routes to `root.controller.js` in `controllersDir`.\n\n#### per-operation\n\nThe mode `per-operation` looks for a `x-controller` tag in operation specification. **It requires the `controllersDir` option.**\n\nExamples:\n```yaml\n\"/pet\":\n  post:\n    summary: Add a new pet to the store\n    x-controller: pets.controller\n    operationId: addPet\n    # This operation routes to `pets.controller` in `controllerDir`\n  put:\n    summary: Update an existing pet\n    x-controller: petupdate.controller\n    operationId: updatePet\n    # This operation routes to `petupdate.controller` in `controllerDir`\n```\n\n#### manual\n\nThe mode `manual` allows to configure how routes will be mapped to controllers. The `resolutionConfig` option is an object where keys could be the route URL, a prefix for the route URL or a `RegExp` that matche the route URL. If not found, it use the `default` to route to the default controller. **It requires the `resolutionConfig` option.**\n\nExamples:\n```typescript\nconst options = {\n    resolution: \"manual\",\n    controllersDir: \"./controllers\",\n    resolutionConfig: {\n        \"/pets\": \"pets.controller\",\n        \"/orders/(.*)/action\": \"orders-action.controller\",\n        \"/orders(.*)\": \"orders.controller\",\n        default: \"default.controller\"\n    }\n};\n```\n\nUsing the configuration below:\n- `/pets` routes to `pets.controller.js` in `controllersDir`.\n- `/pets/:petId` routes to `pets.controller.js` in `controllersDir`.\n- `/pets/getByStatus` routes to `pets.controller.js` in `controllersDir`.\n- `/orders` routes to `orders.controller.js` in `controllersDir`.\n- `/orders/:orderId` routes to `orders.controller.js` in `controllersDir`.\n- `/orders/:orderId/action` routes to `orders-action.controller.js` in `controllersDir`.\n- `/anything` routes to `default.controller.js` in `controllersDir`.\n\n#### unique\n\nThe mode `unique` is the simpler mode. It allows to configure an unique controller for the whole API by using the `controller` option. **It requires the `controller` option.**\n\n#### default resolution\n\nIf the `resolution` option is not provided, the engine will try to look for options to determine the resolution mode:\n\n1. If `controller` is defined, use the `unique` resolution mode.\n2. If `resolutionConfig` is defined, use the `manual` resolution mode.\n3. If `controllersDir` is defined, use the `per-route` resolution mode.\n\n## OpenAPI extensions\n\n#### x-partial\n\n`fastify-oapi` supports the `x-partial` Open API extension which allows to override `required` configuration of JSON Schemas. It is useful to easily allow some operations to returns partial entities while keeping shared schemas intact.\n\nExamples:\n```yaml\n/partial:\n  get:\n    operationId: getPartial\n    summary: x-partial response\n    responses:\n      \"200\":\n        description: partial\n        content:\n          application/json:\n            schema:\n              x-partial: true\n              type: object\n              properties:\n                response:\n                type: string\n              required:\n                - response\n      \"201\":\n        description: partial $ref\n        content:\n          application/json:\n            schema:\n              x-partial: true\n              $ref: \"#/components/schemas/ResponseObject\"\n```\n\n## License\n\nThis project is under MIT License. See the [LICENSE](LICENSE) file for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftouchifyapp%2Ffastify-oapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftouchifyapp%2Ffastify-oapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftouchifyapp%2Ffastify-oapi/lists"}