OpenApiMiddlewareBuilder

A fluent builder for constructing OpenAPI middleware.

This class provides a chainable API for defining OpenAPI documentation for Express routes. It supports defining tags, summaries, descriptions, request bodies, responses, and parameters.

The builder pattern allows for flexible, readable configuration that produces middleware compatible with the express-openapi-validator library.

Example

const middleware = new OpenApiMiddlewareBuilder(options)
  .withTags(["users"])
  .withSummary("Create a new user")
  .withRequestBody<{name: string; email: string}>({
    name: {type: "string", required: true},
    email: {type: "string", format: "email", required: true},
  })
  .withResponse<{id: string; name: string}>(201, {
    id: {type: "string"},
    name: {type: "string"},
  })
  .build();

Constructors

Constructor

new OpenApiMiddlewareBuilder(options): OpenApiMiddlewareBuilder

Creates a new OpenApiMiddlewareBuilder instance.

Parameters

options

Partial<ModelRouterOptions<unknown>>

Router options containing the OpenAPI path configuration

Returns

OpenApiMiddlewareBuilder

Methods

build()

build(): any

Builds and returns the OpenAPI middleware.

This method finalizes the configuration and returns Express middleware that integrates with the OpenAPI documentation system. If no OpenAPI path is configured in options, returns a no-op middleware.

If validation was enabled via withValidation(), returns an array of middleware: [openApiDocMiddleware, validationMiddleware].

Default error responses (400, 401, 403, 404, 405) are automatically merged with the configured responses.

Returns

any

Express middleware function(s) for OpenAPI documentation and optional validation

Example

const middleware = builder
  .withTags(["users"])
  .withResponse(200, {id: {type: "string"}})
  .build();

router.get("/users/:id", middleware, getUserHandler);

---

buildWithSchemas()

buildWithSchemas(): OpenApiBuildResult

Builds and returns the OpenAPI middleware along with schemas.

This method is useful when you want to use asyncHandler's integrated validation instead of separate validation middleware.

Returns

OpenApiBuildResult

Object containing middleware and schemas

Example

const {middleware, bodySchema} = createOpenApiBuilder(options)
  .withRequestBody<{name: string}>({name: {type: "string", required: true}})
  .buildWithSchemas();

router.post("/users", middleware, asyncHandler(async (req, res) => {
  // handler code
}, {bodySchema, validate: true}));

---

withArrayResponse()

withArrayResponse<T>(statusCode, itemSchema, options?): this

Adds an array response definition to the OpenAPI operation.

Use this method when the response is an array of objects rather than a single object.

Type Parameters

T

T extends Record<string, unknown>

Type representing the structure of each array item

Parameters

statusCode

number

HTTP status code for this response

itemSchema

{ [K in string | number | symbol]: OpenApiSchemaProperty }

Schema for each item in the response array

options?

Optional configuration for the response

description?

string

Description of the response (default: "Success")

mediaType?

string

Media type for the response (default: "application/json")

Returns

this

The builder instance for chaining

Example

builder.withArrayResponse<{id: string; name: string}>(200, {
  id: {type: "string"},
  name: {type: "string"},
}, {description: "List of users"});

---

withDescription()

withDescription(description): this

Sets the description for the OpenAPI operation.

The description provides detailed information about the operation, including usage notes, examples, and caveats.

Parameters

description

string

Detailed description of the operation

Returns

this

The builder instance for chaining

Example

builder.withDescription("Retrieves a user by their unique identifier. Returns 404 if not found.");

---

withOperationId()

withOperationId(operationId): this

Sets an explicit operationId for the OpenAPI operation.

The operationId is a unique string used to identify an operation. Client and SDK generators (e.g. RTK Query codegen) derive generated function and hook names from it, so setting it keeps generated names stable and readable for routes whose URL path would otherwise produce unwieldy names (e.g. deeply nested routes). It must be unique across the whole OpenAPI document.

Parameters

operationId

string

Unique operation identifier (e.g. "getUserStats")

Returns

this

The builder instance for chaining

Example

builder.withOperationId("getUserStats");

---

withPathParameter()

withPathParameter(name, schema, options?): this

Adds a path parameter to the OpenAPI operation.

Path parameters are embedded in the URL path (e.g., /users/:id). Path parameters are always required per OpenAPI specification.

Parameters

name

string

Name of the path parameter (must match the route parameter)

schema

OpenApiSchemaProperty

Schema defining the parameter's type and format

options?

Optional configuration for the parameter

description?

string

Human-readable description of the parameter

Returns

this

The builder instance for chaining

Example

builder.withPathParameter("id", {type: "string", format: "uuid"}, {
  description: "Unique identifier of the user",
});

---

withQueryParameter()

withQueryParameter(name, schema, options?): this

Adds a query parameter to the OpenAPI operation.

Query parameters are passed in the URL query string (e.g., ?limit=10).

Parameters

name

string

Name of the query parameter

schema

OpenApiSchemaProperty

Schema defining the parameter's type and format

options?

Optional configuration for the parameter

description?

string

Human-readable description of the parameter

required?

boolean

Whether the parameter is required (default: false)

Returns

this

The builder instance for chaining

Example

builder.withQueryParameter("limit", {type: "number"}, {
  required: false,
  description: "Maximum number of results to return",
});

---

withRequestBody()

withRequestBody<T>(schema, options?): this

Sets the request body schema for the OpenAPI operation.

Properties marked with required: true will be added to the schema's required array automatically.

Type Parameters

T

T extends Record<string, unknown>

Type representing the request body structure

Parameters

schema

{ [K in string | number | symbol]: OpenApiSchemaProperty }

Object mapping property names to their OpenAPI schema definitions

options?

Optional configuration for the request body

mediaType?

string

Media type for the request body (default: "application/json")

required?

boolean

Whether the request body itself is required (default: true)

Returns

this

The builder instance for chaining

Example

builder.withRequestBody<{name: string; age: number}>({
  name: {type: "string", description: "User name", required: true},
  age: {type: "number", description: "User age"},
});

---

withResponse()

withResponse<T>(statusCode, schema, options?): this

Adds a response definition to the OpenAPI operation.

Can accept either an object schema or a simple string description for responses without a body (e.g., 204 No Content).

Type Parameters

T

T extends Record<string, unknown>

Type representing the response body structure

Parameters

statusCode

number

HTTP status code for this response

schema

string | { [K in string | number | symbol]: OpenApiSchemaProperty }

Either an object schema or a description string

options?

Optional configuration for the response

description?

string

Description of the response (default: "Success")

mediaType?

string

Media type for the response (default: "application/json")

Returns

this

The builder instance for chaining

Example

// Response with body
builder.withResponse<{id: string}>(200, {
  id: {type: "string", description: "Created resource ID"},
}, {description: "Resource created successfully"});

// Response without body
builder.withResponse(204, "No content");

---

withSummary()

withSummary(summary): this

Sets the summary for the OpenAPI operation.

The summary is a brief description shown in API documentation listings.

Parameters

summary

string

Short description of the operation

Returns

this

The builder instance for chaining

Example

builder.withSummary("Get user by ID");

---

withTags()

withTags(tags): this

Sets the tags for the OpenAPI operation.

Tags are used to group operations in the API documentation.

Parameters

tags

string[]

Array of tag names

Returns

this

The builder instance for chaining

Example

builder.withTags(["users", "authentication"]);

---

withValidation()

withValidation(options?): this

Enables runtime validation for this route.

When enabled, the built middleware will validate incoming requests against the documented schema before the handler runs.

Parameters

options?

Optional configuration for validation

body?

boolean

Enable body validation (default: true if request body is defined)

enabled?

boolean

Override the global validation enabled setting

query?

boolean

Enable query parameter validation (default: true if query params are defined)

Returns

this

The builder instance for chaining

Example

createOpenApiBuilder(options)
  .withRequestBody<{name: string}>({name: {type: "string", required: true}})
  .withValidation() // Enable validation
  .build();