Express OpenAPI

The ExpressOpenApi function (exported as the default) initializes the OpenAPI middleware. It can be called with several argument combinations to configure the route prefix, the OpenAPI document, and additional options.

Argument patterns:

• oapi(): Uses default prefix (/openapi) and a minimum viable document.
• oapi('/path'): Sets a custom route prefix.
• oapi('/path', doc): Sets a custom prefix and provides an initial OpenAPI document.
• oapi('/path', doc, opts): Sets prefix, document, and configuration options.
• oapi(doc): Uses default prefix and provides a document.
• oapi(doc, opts): Uses default prefix, provides a document, and options.

Options:

• basePath: Used during document generation.
• htmlui: If set to 'swagger-ui', the middleware will automatically set up Swagger UI routes at the routePrefix.

const ExpressOpenApi = require('express-openapi');

// Example: Initialize with a custom prefix and options
const oapi = ExpressOpenApi('/api/docs', myDoc, { basePath: '/api/v1', htmlui: 'swagger-ui' });

// Use in Express
app.use(oapi);

Use .component(type, [name, definition]) to add items to the components section of your OpenAPI document.

Variadic Behavior:

• oapi.component(type, name, definition): Creates a new component.
• oapi.component(type, name): Returns a Reference Object ($ref) pointing to that component.
• oapi.component(type): Returns the full components JSON object.

Specialized Helpers: Instead of calling .component() with a type string, you can use these bound helpers:

• .schema(name, definition)
• .response(name, definition)
• .parameters(name, definition)
• .examples(name, definition)
• .requestBodies(name, definition)
• .headers(name, definition)
• .securitySchemes(name, definition)
• .links(name, definition)
• .callbacks(name, definition)

// Create a component
oapi.component('examples', 'FooExample', {
  summary: 'An example of foo',
  value: 'bar'
})

// Get a reference to a component
const ref = oapi.component('examples', 'FooExample');
// returns { '$ref': '#/components/examples/FooExample' }

The .validPath([definition [, pathOpts]]) method registers a path in the OpenAPI document AND ensures incoming requests are valid against the provided schema.

If validation fails, it calls next(err) with an error created via http-errors. The error object is augmented with:

• err.validationErrors: The error format from ajv.
• err.validationSchema: The schema that failed.

To support custom validation (like ajv-keywords), pass { keywords: [...] } as the second argument (pathOpts).

app.get('/:foo', oapi.validPath({
  description: 'Get a foo',
  responses: {
    200: {
      content: {
        'application/json': {
          schema: {
            type: 'object',
            properties: {
              foo: { type: 'string' }
            }
          }
        }
      }
    }
  }
}), (err, req, res, next) => {
  if (err) {
    res.status(err.status).json({
      error: err.message,
      validation: err.validationErrors,
      schema: err.validationSchema
    })
    return
  }
  res.json({ foo: req.params.foo })
})

The middleware provides helper methods to define and register OpenAPI components (like schemas, parameters, or security schemes) directly into the generated document.

Methods:

• middleware.component(type, name, description): The base method for defining any component type.
• middleware.schema(name, description): Shortcut for component('schemas', ...).
• middleware.response(name, description): Shortcut for component('responses', ...).
• middleware.parameters(name, description): Shortcut for component('parameters', ...).
• middleware.examples(name, description): Shortcut for component('examples', ...).
• middleware.requestBodies(name, description): Shortcut for component('requestBodies', ...).
• middleware.headers(name, description): Shortcut for component('headers', ...).
• middleware.securitySchemes(name, description): Shortcut for component('securitySchemes', ...).
• middleware.links(name, description): Shortcut for component('links', ...).
• middleware.callbacks(name, description): Shortcut for component('callbacks', ...).

Behavior:

• If you provide name and description, it defines a new component.
• If you provide only name, it returns a JSON Reference ($ref) to the existing component.
• If you provide no arguments, it returns the entire collection of that component type.

const oapi = ExpressOpenApi('/openapi', myDoc);

// Define a new schema
oapi.schema('User', { type: 'object', properties: { id: { type: 'string' } } });

// Get a reference to the schema
const userRef = oapi.schema('User'); // returns { $ref: '#/components/schemas/User' }

The middleware provides two ways to attach OpenAPI definitions to specific routes for documentation and validation.

middleware.path(schema)

Registers a schema for a specific path. This is primarily used for documentation purposes to ensure the path is included in the generated OpenAPI document.

middleware.validPath(schema, pathOpts)

Returns a middleware function that validates incoming requests against the provided OpenAPI schema. It uses the internal validator to check the request against the schema.

Note: Both methods return a middleware function that you must then use in your Express route definitions.

const oapi = ExpressOpenApi('/openapi', myDoc);
const userSchema = { type: 'object', properties: { id: { type: 'string' } } };

// For documentation only
app.get('/user/:id', oapi.path(userSchema), (req, res) => {
  res.send('User info');
});

// For documentation AND request validation
app.post('/user', oapi.validPath(userSchema), (req, res) => {
  res.send('User created');
});