![\"openapi-backend\"](\"https://github.com/openapistack/openapi-backend/raw/main/header.png\")
Build, Validate, Route, Authenticate, and Mock using OpenAPI definitions.
\n\nOpenAPI Backend is a Framework-agnostic middleware tool for building beautiful APIs with OpenAPI Specification.
\n\nBattle-tested in production. See who uses openapi-stack →
\n\n## Features\n\n- [x] Build APIs by describing them in [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md)\n- [x] Register handlers for [operationIds](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#fixed-fields-8)\nto route requests in your favourite Node.js backend\n- [x] Use [JSON Schema](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types) to validate\nAPI requests and/or responses. OpenAPI Backend uses the [AJV](https://ajv.js.org/) library under the hood for performant validation\n- [x] Register Auth / Security Handlers for [OpenAPI Security Schemes](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject)\nto authorize API requests\n- [x] Auto-mock API responses using [OpenAPI examples objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#example-object)\nor [JSON Schema definitions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#schema-object)\n- [x] Built with TypeScript, types included\n- [x] Optimised runtime routing and validation. **No generated code!**\n- [x] OpenAPI 3.1 support\n\n## Documentation\n\n**New!** OpenAPI Backend documentation is now found on [openapistack.co](https://openapistack.co)\n\nhttps://openapistack.co/docs/openapi-backend/intro\n\n## Quick Start\n\nFull [example projects](https://github.com/openapistack/openapi-backend/tree/examples) included in the repo (on the `examples` branch)\n\n```\nnpm install --save openapi-backend\n```\n\n```javascript\nimport OpenAPIBackend from 'openapi-backend';\n\n// create api with your definition file or object\nconst api = new OpenAPIBackend({ definition: './petstore.yml' });\n\n// register your framework specific request handlers here\napi.register({\n getPets: (c, req, res) => res.status(200).json({ result: 'ok' }),\n getPetById: (c, req, res) => res.status(200).json({ result: 'ok' }),\n validationFail: (c, req, res) => res.status(400).json({ err: c.validation.errors }),\n notFound: (c, req, res) => res.status(404).json({ err: 'not found' }),\n});\n\n// initalize the backend\napi.init();\n```\n\n### Express\n\n```javascript\nimport express from 'express';\n\nconst app = express();\napp.use(express.json());\napp.use((req, res) => api.handleRequest(req, req, res));\napp.listen(9000);\n```\n\n[See full Express example](https://github.com/openapistack/openapi-backend/tree/examples/express)\n\n[See full Express TypeScript example](https://github.com/openapistack/openapi-backend/tree/examples/express-typescript)\n\n### AWS Serverless (Lambda)\n\n```javascript\n// API Gateway Proxy handler\nmodule.exports.handler = (event, context) =>\n api.handleRequest(\n {\n method: event.httpMethod,\n path: event.path,\n query: event.queryStringParameters,\n body: event.body,\n headers: event.headers,\n },\n event,\n context,\n );\n```\n\n[See full AWS SAM example](https://github.com/openapistack/openapi-backend/tree/examples/aws-sam)\n\n[See full AWS CDK example](https://github.com/openapistack/openapi-backend/tree/examples/aws-cdk)\n\n[See full SST example](https://github.com/openapistack/openapi-backend/tree/examples/aws-sst)\n\n[See full Serverless Framework example](https://github.com/openapistack/openapi-backend/tree/examples/serverless-framework)\n\n### Azure Function\n\n```javascript\nmodule.exports = (context, req) =>\n api.handleRequest(\n {\n method: req.method,\n path: req.params.path,\n query: req.query,\n body: req.body,\n headers: req.headers,\n },\n context,\n req,\n );\n```\n\n[See full Azure Function example](https://github.com/openapistack/openapi-backend/tree/examples/azure-function)\n\n### Fastify\n\n```ts\nimport fastify from 'fastify';\n\nfastify.route({\n method: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],\n url: '/*',\n handler: async (request, reply) =>\n api.handleRequest(\n {\n method: request.method,\n path: request.url,\n body: request.body,\n query: request.query,\n headers: request.headers,\n },\n request,\n reply,\n ),\n});\nfastify.listen();\n```\n\n[See full Fastify example](https://github.com/openapistack/openapi-backend/tree/examples/fastify)\n\n### Hapi\n\n```javascript\nimport Hapi from '@hapi/hapi';\n\nconst server = new Hapi.Server({ host: '0.0.0.0', port: 9000 });\nserver.route({\n method: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],\n path: '/{path*}',\n handler: (req, h) =>\n api.handleRequest(\n {\n method: req.method,\n path: req.path,\n body: req.payload,\n query: req.query,\n headers: req.headers,\n },\n req,\n h,\n ),\n});\nserver.start();\n```\n\n[See full Hapi example](https://github.com/openapistack/openapi-backend/tree/examples/hapi-typescript)\n\n\n### Koa\n\n```javascript\nimport Koa from 'koa';\nimport bodyparser from 'koa-bodyparser';\n\nconst app = new Koa();\n\napp.use(bodyparser());\napp.use((ctx) =>\n api.handleRequest(\n ctx.request,\n ctx,\n ),\n);\napp.listen(9000);\n```\n\n[See full Koa example](https://github.com/openapistack/openapi-backend/tree/examples/koa)\n\n## Registering Handlers for Operations\n\nHandlers are registered for [`operationIds`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.2.md#fixed-fields-8)\nfound in the OpenAPI definitions. You can register handlers as shown above with [`new OpenAPIBackend()`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#parameter-optshandlers)\nconstructor opts, or using the [`register()`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#registeroperationid-handler)\nmethod.\n\n```javascript\nasync function getPetByIdHandler(c, req, res) {\n const id = c.request.params.id;\n const pet = await pets.getPetById(id);\n return res.status(200).json({ result: pet });\n}\napi.register('getPetById', getPetByIdHandler);\n// or\napi.register({\n getPetById: getPetByIdHandler,\n});\n```\n\nOperation handlers are passed a special [Context object](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#context-object)\nas the first argument, which contains the parsed request, the\nmatched API operation and input validation results. The other arguments in the example above are Express-specific\nhandler arguments.\n\n## Request validation\n\nThe easiest way to enable request validation in your API is to register a [`validationFail`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#validationfail-handler)\nhandler.\n\n```javascript\nfunction validationFailHandler(c, req, res) {\n return res.status(400).json({ status: 400, err: c.validation.errors });\n}\napi.register('validationFail', validationFailHandler);\n```\n\nOnce registered, this handler gets called if any JSON Schemas in either operation parameters (in: path, query, header,\ncookie) or requestPayload don't match the request.\n\nThe context object `c` gets a `validation` property with the [validation result](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#validationresult-object).\n\n### Controlling when requests get validated\n\nRequest validation is enabled by default. Pass `validate: false` to turn it off entirely, which also skips building the\nAjv validators at startup.\n\n```javascript\nconst api = new OpenAPIBackend({ definition: './petstore.yml', validate: false });\n```\n\nYou can also pass a predicate to decide per request. It receives the context object followed by the same handler\narguments you pass to `handleRequest`, and validation runs only when it returns `true`.\n\n```javascript\nconst api = new OpenAPIBackend({\n definition: './petstore.yml',\n // skip validation for internal traffic, validate everything else\n validate: (c, req, res) => !req.headers['x-internal-request'],\n});\n\napi.handleRequest(req, req, res);\n```\n\nNote that type coercion happens as part of validation, so when `coerceTypes` is enabled, requests your predicate skips\nwon't have their path and query parameters coerced either.\n\n## Response validation\n\nOpenAPIBackend doesn't automatically perform response validation for your handlers, but you can register a\n[`postResponseHandler`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#postresponsehandler-handler)\nto add a response validation step using [`validateResponse`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#validateresponseres-operation).\n\n```javascript\napi.register({\n getPets: (c) => {\n // when a postResponseHandler is registered, your operation handlers' return value gets passed to context.response\n return [{ id: 1, name: 'Garfield' }];\n },\n postResponseHandler: (c, req, res) => {\n const valid = c.api.validateResponse(c.response, c.operation);\n if (valid.errors) {\n // response validation failed\n return res.status(502).json({ status: 502, err: valid.errors });\n }\n return res.status(200).json(c.response);\n },\n});\n```\n\nIt's also possible to validate the response headers using [`validateResponseHeaders`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#validateresponseheadersheaders-operation-opts).\n\n```javascript\napi.register({\n getPets: (c) => {\n // when a postResponseHandler is registered, your operation handlers' return value gets passed to context.response\n return [{ id: 1, name: 'Garfield' }];\n },\n postResponseHandler: (c, req, res) => {\n const valid = c.api.validateResponseHeaders(res.headers, c.operation, {\n statusCode: res.statusCode,\n setMatchType: 'exact',\n });\n if (valid.errors) {\n // response validation failed\n return res.status(502).json({ status: 502, err: valid.errors });\n }\n return res.status(200).json(c.response);\n },\n});\n```\n\n## Auth / Security Handlers\n\nIf your OpenAPI definition contains [Security Schemes](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject)\nyou can register security handlers to handle authorization for your API:\n\n```yaml\ncomponents:\n securitySchemes:\n - ApiKey:\n type: apiKey\n in: header\n name: x-api-key\nsecurity:\n - ApiKey: []\n```\n\n```javascript\napi.registerSecurityHandler('ApiKey', (c) => {\n const authorized = c.request.headers['x-api-key'] === 'SuperSecretPassword123';\n // truthy return values are interpreted as auth success\n // you can also add any auth information to the return value\n return authorized;\n});\n```\n\nThe authorization status and return values of each security handler can be\naccessed via the [Context Object](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#context-object)\n\nYou can also register an [`unauthorizedHandler`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#unauthorizedhandler-handler)\nto handle unauthorized requests.\n\n```javascript\napi.register('unauthorizedHandler', (c, req, res) => {\n return res.status(401).json({ err: 'unauthorized' })\n});\n```\n\n**Important:** security handlers compute the authorization result and expose it as `context.security.authorized`. They\ndon't stop request handling on their own. To reject unauthorized requests, register an `unauthorizedHandler` or set\n`strict: true`, which makes `handleRequest` reject with a `401-unauthorized` error instead. Without either, the matched\noperation handler still runs (you get warned once) and is responsible for checking `context.security.authorized`. The\nsame applies to request validation and the `validationFail` handler. See [SECURITY.md](SECURITY.md) for the full contract.\n\nSee examples:\n- [API Key auth (express)](https://github.com/openapistack/openapi-backend/tree/examples/express-apikey-auth)\n- [JWT auth (express)](https://github.com/openapistack/openapi-backend/tree/examples/express-jwt-auth)\n\n## Mocking API responses\n\nMocking APIs just got really easy with OpenAPI Backend! Register a [`notImplemented`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md#notimplemented-handler)\nhandler and use [`mockResponseForOperation()`](https://github.com/openapistack/openapi-backend/blob/main/DOCS.md##mockresponseforoperationoperationid-opts)\nto generate mock responses for operations with no custom handlers specified yet:\n\n```javascript\napi.register('notImplemented', (c, req, res) => {\n const { status, mock } = c.api.mockResponseForOperation(c.operation.operationId);\n return res.status(status).json(mock);\n});\n```\n\nOpenAPI Backend supports mocking responses using both OpenAPI example objects and JSON Schema:\n```yaml\npaths:\n '/pets':\n get:\n operationId: getPets\n summary: List pets\n responses:\n 200:\n $ref: '#/components/responses/PetListWithExample'\n '/pets/{id}':\n get:\n operationId: getPetById\n summary: Get pet by its id\n responses:\n 200:\n $ref: '#/components/responses/PetResponseWithSchema'\ncomponents:\n responses:\n PetListWithExample:\n description: List of pets\n content:\n 'application/json':\n example:\n - id: 1\n name: Garfield\n - id: 2\n name: Odie\n PetResponseWithSchema:\n description: A single pet\n content:\n 'application/json':\n schema:\n type: object\n properties:\n id:\n type: integer\n minimum: 1\n name:\n type: string\n example: Garfield\n```\n\nThe example above will yield:\n```javascript\napi.mockResponseForOperation('getPets'); // => { status: 200, mock: [{ id: 1, name: 'Garfield' }, { id: 2, name: 'Odie' }]}\napi.mockResponseForOperation('getPetById'); // => { status: 200, mock: { id: 1, name: 'Garfield' }}\n```\n\n[See full Mock API example on Express](https://github.com/openapistack/openapi-backend/tree/examples/express-ts-mock)\n\n## Software Bill of Materials\n\nA [CycloneDX](https://cyclonedx.org) SBOM for the published package is maintained in [`sbom/openapi-backend.cdx.json`](sbom/openapi-backend.cdx.json), alongside a [full-tree variant](sbom/openapi-backend.full.cdx.json) that includes devDependencies and CSV license listings. Third-party licenses and copyright holders are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n\nTo browse the SBOM interactively, open [CycloneDX Sunshine](https://cyclonedx.github.io/Sunshine/) and load the JSON file.\n\nRegenerate after dependency changes with:\n\n```\nnpm run sbom\n```\n\n## Commercial support\n\nFor assistance with integrating openapi-backend in your company, reach out at support@openapistack.co.\n\n## Contributing\n\nOpenAPI Backend is Free and Open Source Software. Issues and pull requests are more than welcome!\n\n","readmeFilename":"README.md"}