OpenAPI Backend

Common errors

• TypeError: OpenAPIBackend is not a constructor

  cause Attempting to use `require()` for a library that is primarily ESM-first, or not correctly importing the default export.
  fix Use ESM `import OpenAPIBackend from 'openapi-backend';` instead of CommonJS `const OpenAPIBackend = require('openapi-backend');`.

• Error: request validation failed

  cause The incoming API request (parameters, headers, body) does not conform to the schema defined in your OpenAPI Specification.
  fix Inspect `c.validation.errors` within your `validationFail` handler to understand the specific schema violations. Adjust the incoming request or the OpenAPI definition accordingly.

• Error: notFound

  cause No `operationId` in your OpenAPI definition matches the incoming request path and method, and a generic `notFound` handler has been triggered.
  fix Verify your OpenAPI definition's `paths` and `operationIds` align with expected API endpoints. Ensure you have registered a handler for the relevant `operationId` or a catch-all `notFound` handler.

Warnings

• breaking Starting with version 5.x, `openapi-backend` requires Node.js version 20.0.0 or higher. Older Node.js versions are not supported.
  Fix: Upgrade your Node.js environment to version 20.0.0 or later.
• gotcha When using `openapi-backend` in a TypeScript project, ensure you use `import type` for importing types (e.g., `Context`, `Request`, `Response`) to prevent issues with runtime imports, especially in environments that don't correctly handle type-only imports.
  Fix: Change `import { TypeName } from 'openapi-backend';` to `import type { TypeName } from 'openapi-backend';` for all type imports.
• gotcha The `api.init()` method must be called after registering all handlers and before handling any requests. Failing to call `init()` will prevent the API backend from properly loading your OpenAPI definition and routing requests.
  Fix: Ensure `api.init()` is invoked once after `api.register()` calls and before any `api.handleRequest()` calls.

Install

• npm install openapi-backend npm
• yarn add openapi-backend yarn
• pnpm add openapi-backend pnpm

Imports

• OpenAPIBackend
  wrong:

  const OpenAPIBackend = require('openapi-backend');

  correct:

  import OpenAPIBackend from 'openapi-backend';

  OpenAPIBackend is a default export. The library is primarily designed for ESM environments, especially with its Node.js >=20 requirement; CommonJS `require` is generally not recommended.
• Context
  wrong:

  import { Context } from 'openapi-backend';

  correct:

  import type { Context } from 'openapi-backend';

  The `Context` object, containing request, validation, and security details, is passed to all registered operation handlers. It is a TypeScript type, so `import type` is preferred to avoid runtime import issues.
• Request, Response
  wrong:

  import { Request, Response } from 'openapi-backend';

  correct:

  import type { Request, Response } from 'openapi-backend';

  These are generic TypeScript interfaces for handler arguments, allowing for type-safe interaction while remaining framework-agnostic. They are types, so `import type` is correct.

Quickstart

This code snippet demonstrates the fundamental steps to initialize `openapi-backend` from an OpenAPI definition (here, a minimal inline one), register custom handlers for specific API operations (like `getPets` and `getPetById`), and implement generic handlers for validation failures and unmatched routes. It then integrates this setup with an Express application, showing how to connect the library's routing and validation logic to custom application logic, providing a basic functional API.

import OpenAPIBackend from 'openapi-backend';
import express from 'express';

// In a real application, './petstore.yml' would be your OpenAPI definition file.
// For demonstration, we'll use a minimal inline definition.
const api = new OpenAPIBackend({
  definition: {
    openapi: '3.0.0',
    info: { title: 'Petstore API', version: '1.0.0' },
    paths: {
      '/pets': {
        get: {
          operationId: 'getPets',
          responses: { 200: { description: 'A list of pets' } },
        },
      },
      '/pets/{petId}': {
        get: {
          operationId: 'getPetById',
          parameters: [
            { name: 'petId', in: 'path', required: true, schema: { type: 'string' } },
          ],
          responses: { 200: { description: 'A single pet' } },
        },
      },
    },
  },
});

// register your framework specific request handlers here
api.register({
  getPets: (c, req, res) => res.status(200).json({ result: 'all pets' }),
  getPetById: (c, req, res) => res.status(200).json({ result: `pet with id ${c.request.params.petId}` }),
  validationFail: (c, req, res) => res.status(400).json({ err: c.validation.errors }),
  notFound: (c, req, res) => res.status(404).json({ err: 'not found' }),
});

// initalize the backend
api.init();

const app = express();
app.use(express.json()); // Enable JSON body parsing

// Connect openapi-backend to your Express application
app.use((req, res) => api.handleRequest(req, req, res));

const PORT = process.env.PORT ?? 9000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log('Try visiting: http://localhost:9000/pets');
  console.log('Try visiting: http://localhost:9000/pets/123');
});