[zod-openapi] Clarification and Support for Validating Bearer Tokens in Headers Using Zod Without Overlapping Definitions

[xalidmalik]

Hello,

I am encountering a challenge while setting up Bearer token authentication with validation using Zod in conjunction with the library’s createRoute function. While the documentation provides guidance on registering the security scheme and defining security for specific routes, there are some gaps when it comes to header validation and avoiding overlapping header definitions.

I am setting up authorization as follows:

1. Registering the security scheme:

app.openAPIRegistry.registerComponent("securitySchemes", "Bearer", {
  type: "http",
  scheme: "bearer",
  bearerFormat: "JWT",
});

2. Creating an authentication-aware route factory:

export const createAuthController = <P extends string, R extends Omit<RouteConfig, "path">>(
  routeConfig: R & { path: P }
) =>
  createRoute({
    request: {
      ...routeConfig.request,
    },
    security: [
      {
        Bearer: [],
      },
    ],
    ...routeConfig,
    responses: {
      [HttpStatusCodes.UNAUTHORIZED]: jsonContent(
        z.object({
          message: z.string().openapi({ example: HttpStatusPhrases.UNAUTHORIZED }),
        }),
        HttpStatusPhrases.UNAUTHORIZED
      ),
      ...routeConfig.responses,
    },
  });

3. When I want to enforce Zod validation to ensure the presence of the Authorization header and validate its format, I attempt to add the following to the request configuration:

request: {
  headers: z.object({
    authorization: z.string().min(4), // Example to ensure that a bearer token is provided in the header
  }),
  ...routeConfig.request,
},

The Problem:

• When I include the above code for request.headers, the generated OpenAPI documentation shows two overlapping header definitions:
• One from the security configuration (Bearer).
• Another from the explicit headers validation added using z.object.

This creates redundancy in the documentation and could confuse

Expected Behavior:

• A straightforward way to validate the presence and format of the Authorization header using Zod.
• Ensure the validation logic is reflected in the OpenAPI documentation.
• Avoid duplication or overlapping definitions for headers in the documentation when combining the security property and request.headers.

Questions:

1. Is there an officially recommended approach to integrate Zod validation for headers while leveraging security schemes without causing overlaps in the documentation?
2. Could the library support a default header validator for registered securitySchemes, so manual addition of request.headers becomes unnecessary?
3. Is there any existing support for enhancing the security definition to include such validation directly?

Thank you for your assistance and guidance! I am looking forward to your feedback. 😊