{"_id":"@autotelic/fastify-openapi-autoload","_rev":"3-ab9e2e7de448e7166370cc95d0fb2750","name":"@autotelic/fastify-openapi-autoload","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@autotelic/fastify-openapi-autoload","version":"0.1.0","keywords":[],"author":{"name":"Autotelic Development Ltd","email":"info@autotelic.com"},"license":"MIT","_id":"@autotelic/fastify-openapi-autoload@0.1.0","maintainers":[{"name":"autotelic","email":"info+npm@autotelic.com"}],"homepage":"https://github.com/autotelic/fastify-openapi-autoload#readme","bugs":{"url":"https://github.com/autotelic/fastify-openapi-autoload/issues"},"tsd":{"directory":"types"},"dist":{"shasum":"e4fe01cb61d3c9996ace482c011c94e1b67067d3","tarball":"https://registry.npmjs.org/@autotelic/fastify-openapi-autoload/-/fastify-openapi-autoload-0.1.0.tgz","fileCount":8,"integrity":"sha512-KDkje3rIIfxHxn7qmkTTHu8UsSwsWQjXvDo3IbkHbWvrQDlfs0NVoFP7oOUUZqBBkwNliS/FZa/4TUtIV4faaA==","signatures":[{"sig":"MEYCIQC5MIhC9qmaFyla83+K+WfuKMLcpHSxu0NlY2GgXGA1DAIhAMmKlofS0ru87D/nQvaClqCRI4E6q2N2DDnBEw9TGiu1","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":15122},"main":"index.js","type":"module","types":"types/index.d.ts","engines":{"node":">=18"},"gitHead":"b32e89c0777a8943bedd0997961f5e39ea68958e","scripts":{"lint":"eslint .","test":"tap","validate":"npm run lint && npm run test && npm run test:types","test:types":"tsd"},"_npmUser":{"name":"autotelic","email":"info+npm@autotelic.com"},"repository":{"url":"git+https://github.com/autotelic/fastify-openapi-autoload.git","type":"git"},"_npmVersion":"10.2.3","description":"Plugin for fastify","directories":{},"_nodeVersion":"18.19.0","dependencies":{"yamljs":"^0.3.0","json-refs":"^3.0.15","fastify-plugin":"^4.5.1","@fastify/autoload":"^5.8.0","fastify-openapi-glue":"4.4.2"},"_hasShrinkwrap":false,"devDependencies":{"tap":"^18.6.1","tsd":"^0.30.3","jose":"^5.2.0","nock":"^13.5.0","eslint":"^8.56.0","fastify":"^4.25.2","fast-jwt":"^3.3.2","typescript":"^5.3.3","@typescript-eslint/parser":"^7.0.2","@autotelic/eslint-config-js":"^0.3.0","@autotelic/fastify-injector":"^0.3.0","@typescript-eslint/eslint-plugin":"^7.0.2","eslint-import-resolver-typescript":"^3.6.1"},"peerDependencies":{"get-jwks":"^9.0.0","@fastify/jwt":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/fastify-openapi-autoload_0.1.0_1708540501093_0.5745774686264176","host":"s3://npm-registry-packages"}},"0.2.0":{"name":"@autotelic/fastify-openapi-autoload","version":"0.2.0","keywords":[],"author":{"name":"Autotelic Development Ltd","email":"info@autotelic.com"},"license":"MIT","_id":"@autotelic/fastify-openapi-autoload@0.2.0","maintainers":[{"name":"autotelic","email":"info+npm@autotelic.com"}],"homepage":"https://github.com/autotelic/fastify-openapi-autoload#readme","bugs":{"url":"https://github.com/autotelic/fastify-openapi-autoload/issues"},"tsd":{"directory":"types"},"dist":{"shasum":"745c92914a176bb887659b5080614bd629c062d2","tarball":"https://registry.npmjs.org/@autotelic/fastify-openapi-autoload/-/fastify-openapi-autoload-0.2.0.tgz","fileCount":8,"integrity":"sha512-TlJfn5K6na7i15omrHwNUqvBvKNcds5pMK/j4npWzAOlVc2lbrwie8wDSfLU2mCfwbNNG/i9kFymXnaQxKb3DA==","signatures":[{"sig":"MEQCIAhPUoQx8jaDyWNYL+6tdrogP/OCYGlbvq7VvWeW4Nk8AiBUb68SGFrOmN0+CxjuOcxhIHCTRY+WiUqMS/Tfxo1vkQ==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":15106},"main":"index.js","type":"module","types":"types/index.d.ts","engines":{"node":">=18"},"gitHead":"7f8f005d86199159f9822003bce6b7cc8eb7d596","scripts":{"lint":"eslint .","test":"tap","validate":"npm run lint && npm run test && npm run test:types","test:types":"tsd"},"_npmUser":{"name":"autotelic","email":"info+npm@autotelic.com"},"repository":{"url":"git+https://github.com/autotelic/fastify-openapi-autoload.git","type":"git"},"_npmVersion":"10.2.3","description":"Plugin for fastify","directories":{},"_nodeVersion":"18.19.0","dependencies":{"yamljs":"^0.3.0","json-refs":"^3.0.15","fastify-plugin":"^4.5.1","@fastify/autoload":"^5.8.0","fastify-openapi-glue":"^4.4.3"},"_hasShrinkwrap":false,"devDependencies":{"tap":"^18.6.1","tsd":"^0.30.3","jose":"^5.2.0","nock":"^13.5.0","eslint":"^8.56.0","fastify":"^4.25.2","fast-jwt":"^4.0.0","typescript":"^5.3.3","@typescript-eslint/parser":"^7.0.2","@autotelic/eslint-config-js":"^0.3.0","@autotelic/fastify-injector":"^0.3.0","@typescript-eslint/eslint-plugin":"^7.0.2","eslint-import-resolver-typescript":"^3.6.1"},"peerDependencies":{"get-jwks":"^9.0.0","@fastify/jwt":"^8.0.0"},"_npmOperationalInternal":{"tmp":"tmp/fastify-openapi-autoload_0.2.0_1710455880238_0.1577881250440043","host":"s3://npm-registry-packages"}},"0.3.0":{"name":"@autotelic/fastify-openapi-autoload","version":"0.3.0","description":"Plugin for fastify","main":"index.js","types":"types/index.d.ts","type":"module","engines":{"node":">=18"},"scripts":{"lint":"eslint .","test":"tap","test:types":"tsd","validate":"npm run lint && npm run test && npm run test:types"},"repository":{"type":"git","url":"git+https://github.com/autotelic/fastify-openapi-autoload.git"},"keywords":[],"author":{"name":"Autotelic Development Ltd","email":"info@autotelic.com"},"license":"MIT","bugs":{"url":"https://github.com/autotelic/fastify-openapi-autoload/issues"},"homepage":"https://github.com/autotelic/fastify-openapi-autoload#readme","dependencies":{"@fastify/autoload":"^5.9.0","fastify-openapi-glue":"^4.4.3","fastify-plugin":"^4.5.1","json-refs":"^3.0.15","yamljs":"^0.3.0"},"devDependencies":{"@autotelic/fastify-injector":"^0.3.0","@typescript-eslint/eslint-plugin":"^7.0.2","@typescript-eslint/parser":"^7.0.2","eslint":"^8.56.0","eslint-config-standard":"^17.1.0","eslint-import-resolver-typescript":"^3.6.1","eslint-plugin-import":"^2.32.0","eslint-plugin-n":"^16.6.2","eslint-plugin-promise":"^6.6.0","fast-jwt":"^4.0.0","fastify":"^4.25.2","jose":"^5.2.0","nock":"^13.5.0","tap":"^19.2.5","tsd":"^0.30.3","typescript":"^5.3.3"},"peerDependencies":{"@fastify/jwt":"^8.0.0","get-jwks":"^9.0.0"},"tsd":{"directory":"types"},"_id":"@autotelic/fastify-openapi-autoload@0.3.0","gitHead":"c1e73e94e33c16f4c511016fde87e4e66a8934f8","_nodeVersion":"18.19.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-dreaM0m0ytxuy95C2Of1xp1K6m89JGBXFfnX3qqG12oReDIT2ol6/ntcWHfusbVrp0ydR0mZnlefMgpC/Q9/ig==","shasum":"ec40ebb03987b8ad459e8bef93cb6052f2686a70","tarball":"https://registry.npmjs.org/@autotelic/fastify-openapi-autoload/-/fastify-openapi-autoload-0.3.0.tgz","fileCount":8,"unpackedSize":15315,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFZdgh0tDBKCDyxwqm/AE2HJJ4a80B3TUJULO3U+LaJiAiEAnXjjefQFUTJeJihOAy5JamenHId0MSSYXpE3K34NImg="}]},"_npmUser":{"name":"autotelic","email":"info+npm@autotelic.com"},"directories":{},"maintainers":[{"name":"autotelic","email":"info+npm@autotelic.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fastify-openapi-autoload_0.3.0_1752517302147_0.7057093323117698"},"_hasShrinkwrap":false}},"time":{"created":"2024-02-21T18:35:00.981Z","modified":"2025-07-14T18:21:42.510Z","0.1.0":"2024-02-21T18:35:01.352Z","0.2.0":"2024-03-14T22:38:00.446Z","0.3.0":"2025-07-14T18:21:42.327Z"},"bugs":{"url":"https://github.com/autotelic/fastify-openapi-autoload/issues"},"author":{"name":"Autotelic Development Ltd","email":"info@autotelic.com"},"license":"MIT","homepage":"https://github.com/autotelic/fastify-openapi-autoload#readme","keywords":[],"repository":{"type":"git","url":"git+https://github.com/autotelic/fastify-openapi-autoload.git"},"description":"Plugin for fastify","maintainers":[{"name":"autotelic","email":"info+npm@autotelic.com"}],"readme":"# Fastify OpenAPI Autoload\n\nThe `fastify-openapi-autoload` plugin is a tool for building API servers with Fastify, leveraging OpenAPI specifications. It integrates [`fastify-openapi-glue`](https://github.com/seriousme/fastify-openapi-glue) for handling OpenAPI specs and [`@fastify/autoload`](https://github.com/fastify/fastify-autoload) for auto-loading route handlers.\n\n## Features\n\n- **OpenAPI Integration**: Utilizes `fastify-openapi-glue` to automatically handle routes as defined in your OpenAPI spec.\n- **Automatic Route Handlers Loading**: Loads route handlers from a specified directory, significantly reducing route setup code.\n\n## Installation\n\nTo install the plugin, run:\n\n```sh\nnpm i @autotelic/fastify-openapi-autoload\n```\n\n## Prerequisites\n\n- Node.js\n- Fastify\n- OpenAPI specification file\n- Directory with Fastify OpenAPI route handlers\n\n## Example\n\n```js\nimport fastify from 'fastify'\nimport openapiAutoload from '@autotelic/fastify-openapi-autoload'\n\nexport default async function app (fastify, options) {\n  fastify.register(openapiAutoload, {\n    handlersDir: '/path/to/handlers',\n    openapiOpts: {\n      specification: '/path/to/openapi/spec.yaml'\n    }\n  })\n}\n```\n\nTo run an example app, see [this guide](./example/README.md)\n\n## API Reference - Options\n\n### `handlersDir` (required)\n\nPath to the route handlers directory.\n\n ```js\n// example:\n export default async function app (fastify, options) {\n  fastify.register(openapiAutoload, {\n    handlersDir: '/path/to/handlers',\n    // Other configuration options...\n  })\n}\n ```\n\n### `openapiOpts` (required)\n\nOpenAPI-related options. Refer to [fastify-openapi-glue documentation](https://github.com/seriousme/fastify-openapi-glue?tab=readme-ov-file#options) for more details. At minimum, `specification` must be defined. This can be a JSON object, or the path to a JSON or YAML file containing a valid OpenApi(v2/v3) file. If `specification` is a path to a yaml file, `fastify-openapi-autoload` supports multi-file resolving. See [this test directory](./test/fixtures/multi-file-spec/) for example.\n\n ```js\n// example\n export default async function app (fastify, options) {\n  fastify.register(openapiAutoload, {\n    openapiOpts: {\n      specification: '/path/to/spec/openapi.yaml'\n    },\n    // Other configuration options...\n  })\n}\n ```\n\n### `makeOperationResolver` (optional)\n\nBy default, the `fastify-openapi-autoload` provides a standard resolver that locates a handler based on the operation ID, looking for a matching decorator method in the Fastify instance. However, if your application requires a different mapping strategy or additional logic for resolving operations, you can provide a custom resolver function.\n\nThe custom resolver should be a factory function that receives the Fastify instance as an argument and returns an operation resolver function. This resolver function, when invoked with an `operationId`, should return the corresponding handler function for that specific operation.\n\nFor more information on the operation resolver, refer to the [`fastify-openapi-glue operation resolver documentation`](https://github.com/seriousme/fastify-openapi-glue/blob/master/docs/operationResolver.md).\n\n ```js\n// example\nexport default async function app (fastify, options) {\n  fastify.register(openapiAutoload, {\n    makeOperationResolver: (fastify) => (operationId) => {\n      // Custom logic to determine the handler function for the given operationId\n      // For example, returning a fixed response for demonstration:\n      return async (_req, reply) => {\n        reply.code(200).send(`Custom response for operation ${operationId}`)\n      }\n    },\n    // Other configuration options...\n  })\n}\n ```\n\n### `makeSecurityHandlers` (optional)\n\nIf your application requires custom security handlers for your OpenAPI handlers, you can provide a factory function similar to the `makeOperationResolver` option.\n\nThis factory function should take the Fastify instance as an argument and return an object containing the security handlers. Each handler within this object should implement the logic for handling security aspects as defined in your OpenAPI specification.\n\nFor guidance on implementing security handlers, see the [`fastify-openapi-glue security handlers documentation`](https://github.com/seriousme/fastify-openapi-glue/blob/master/docs/securityHandlers.md).\n\nExample usage:\n\n```js\n// example\nexport default async function app (fastify, options) {\n  fastify.register(openapiAutoload, {\n    makeSecurityHandlers: (fastify) => {\n      // Custom logic for security handlers\n      return {\n        someSecurityHandler: (notOk) => {\n          if (notOk) {\n            throw new Error('not ok')\n          }\n        }\n      }\n    },\n    // Other configuration options...\n  })\n}\n```\n\n## JSON Web Token Security Handler\n\nThe `jwtJwksHandler` function, exported with the `fastify-openapi-autoload` plugin, allows you to integrate JWT/JWKS authentication as security handlers.\n\nTo use this function, you need to install the following dependencies:\n\n```sh\nnpm i @autotelic/fastify-openapi-autoload @fastify/jwt get-jwks\n```\n\n### Options\n\nWhen configuring `jwtJwksHandler`, you can customize its behavior with the following options:\n\n- `jwksOpts` (optional): See [`get-jwks` documentation](https://github.com/nearform/get-jwks) for details.\n- `issuer` (*required): The issuer URL of the JWT tokens. This is typically the base URL of the token provider. Required option if `jwksOpts.issuersWhitelist` & `jwksOpts.checkIssuer` options are not provided.\n- `authRequestDecorator` (optional - default provided): A function to decorate the Fastify request with custom JWT authentication logic.\n- `securityHandlers` (optional - default provided): An object containing Fastify security handlers.\n\n### Example Usage\n\n```js\nimport fastify from 'fastify'\nimport openapiAutoload from '@autotelic/fastify-openapi-autoload'\nimport { jwtJwksHandler } from '@autotelic/fastify-openapi-autoload/jwtJwks'\n\nexport default async function app (fastify, options) {\n  const makeSecurityHandlers = jwtJwksHandler({\n    issuer: 'https://your-issuer-url.com',\n    jwksOpts: {\n      max: 100,\n      ttl: 60000,\n      timeout: 5000\n      // ...additional JWKS options\n    },\n    // Custom authentication request decorator (optional)\n    authRequestDecorator: async (request) => {\n      try {\n        const decodedToken = await request.jwtVerify(request)\n        const { userId } = decodedToken\n        return userId\n      } catch (err) {\n        return null\n      }\n    }\n  })\n\n  fastify.register(openapiAutoload, {\n    handlersDir: '/path/to/handlers',\n    openapiOpts: {\n      specification: '/path/to/openapi/spec.yaml'\n    },\n    makeSecurityHandlers\n  })\n}\n```\n\n## Plugin Development: Triggering a Release\n\nTo trigger a new release:\n\n  ```sh\n  git checkout main && git pull\n  npm version { minor | major | patch }\n  git push --follow-tags\n  ```\n","readmeFilename":"README.md"}