hono-openapi 1.3.0 → 1.3.2

package/dist/index.cjs

@@ -6,6 +6,7 @@ var standardJson = require('@standard-community/standard-json');
 var standardOpenapi = require('@standard-community/standard-openapi');
 
 const uniqueSymbol = Symbol("openapi");
+const VALIDATION_MARKER = "__HonoOpenAPIValidator__";
 const ALLOWED_METHODS = [
   "GET",
   "PUT",
@@ -58,7 +59,9 @@ const specsByPathContext = /* @__PURE__ */ new Map();
 function getPathContext(path) {
   const context = [];
   for (const [key, data] of specsByPathContext) {
-    if (data && path.match(key)) {
+    if (!data) continue;
+    const prefix = key.endsWith("/*") ? key.slice(0, -2) : key;
+    if (path === prefix || path.startsWith(`${prefix}/`)) {
       context.push(data);
     }
   }
@@ -159,6 +162,8 @@ function removeExcludedPaths(paths, ctx) {
     for (const method of Object.keys(value)) {
       const schema = value[method];
       if (schema == null) continue;
+      const hasValidation = schema[VALIDATION_MARKER] === true;
+      delete schema[VALIDATION_MARKER];
       if (key.includes("{")) {
         schema.parameters = schema.parameters ? [...schema.parameters] : [];
         const pathParameters = key.split("/").filter(
@@ -198,6 +203,16 @@ function removeExcludedPaths(paths, ctx) {
           200: {}
         };
       }
+      if (hasValidation && ctx.options.defaultValidationErrorResponse !== false && !schema.responses["400"]) {
+        const errorResponse = ctx.options.defaultValidationErrorResponse;
+        if (typeof errorResponse === "object") {
+          schema.responses["400"] = structuredClone(errorResponse);
+        } else if (ctx.validationErrorResponse) {
+          schema.responses["400"] = structuredClone(
+            ctx.validationErrorResponse
+          );
+        }
+      }
     }
     const filteredValue = {};
     for (const method of Object.keys(value)) {
@@ -217,7 +232,27 @@ const DEFAULT_OPTIONS = {
   excludeStaticFile: true,
   exclude: [],
   excludeMethods: ["OPTIONS"],
-  excludeTags: []
+  excludeTags: [],
+  defaultValidationErrorResponse: true
+};
+const DEFAULT_VALIDATION_ERROR = {
+  description: "Validation Error",
+  content: {
+    "application/json": {
+      schema: {
+        type: "object",
+        properties: {
+          success: { type: "boolean", enum: [false] },
+          error: {
+            type: "array",
+            items: {}
+          },
+          data: {}
+        },
+        required: ["success", "error", "data"]
+      }
+    }
+  }
 };
 function openAPIRouteHandler(hono, options) {
   let specs;
@@ -234,9 +269,14 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     options: {
       ...DEFAULT_OPTIONS,
       ...options
-    }
+    },
+    validationErrorResponse: DEFAULT_VALIDATION_ERROR
   };
   const _documentation = ctx.options.documentation ?? {};
+  const documentation = {
+    ..._documentation,
+    components: _documentation.components && { ..._documentation.components }
+  };
   clearSpecsContext();
   const paths = await generatePaths(hono, ctx);
   for (const path in paths) {
@@ -252,27 +292,30 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       }
     }
   }
-  const { components: resolvedDocComponents } = _documentation.components?.responses ? await resolveResponseSchemas(_documentation.components.responses) : { components: {} };
+  const resolvedDocumentation = documentation.components?.responses ? await resolveResponseSchemas(documentation.components.responses) : void 0;
+  if (resolvedDocumentation && documentation.components) {
+    documentation.components.responses = resolvedDocumentation.responses;
+  }
   const components = mergeComponentsObjects(
-    _documentation.components,
-    resolvedDocComponents,
+    documentation.components,
+    resolvedDocumentation?.components,
     ctx.components
   );
   return {
     openapi: "3.1.0",
-    ..._documentation,
-    tags: _documentation.tags?.filter(
+    ...documentation,
+    tags: documentation.tags?.filter(
       (tag) => !ctx.options.excludeTags?.includes(tag?.name)
     ),
     info: {
       title: "Hono Documentation",
       description: "Development documentation",
       version: "0.0.0",
-      ..._documentation.info
+      ...documentation.info
     },
     paths: {
       ...removeExcludedPaths(paths, ctx),
-      ..._documentation.paths
+      ...documentation.paths
     },
     components
   };
@@ -338,12 +381,27 @@ async function getSpec(middlewareHandler, defaultOptions) {
     let components = {};
     if (tmp.responses) {
       const resolved = await resolveResponseSchemas(tmp.responses);
+      tmp.responses = resolved.responses;
       components = resolved.components;
     }
+    if (tmp.requestBody && "content" in tmp.requestBody) {
+      const resolved = await resolveContentSchemas(tmp.requestBody.content);
+      tmp.requestBody = {
+        ...tmp.requestBody,
+        content: resolved.content
+      };
+      components = mergeComponentsObjects(components, resolved.components);
+    }
     return { schema: tmp, components };
   }
   const result = await middlewareHandler.toOpenAPISchema();
-  const docs = { ...defaultOptions };
+  liftSchemaDefs(result);
+  const docs = {
+    ...defaultOptions,
+    // Mark this operation as validator-derived so a default 400 validation
+    // error response can be auto-injected later (see removeExcludedPaths).
+    [VALIDATION_MARKER]: true
+  };
   if (middlewareHandler.target === "form" || middlewareHandler.target === "json") {
     const media = middlewareHandler.options?.media ?? middlewareHandler.target === "json" ? "application/json" : "multipart/form-data";
     if (!docs.requestBody || !("content" in docs.requestBody) || !docs.requestBody.content) {
@@ -381,51 +439,113 @@ async function getSpec(middlewareHandler, defaultOptions) {
         });
       }
     } else {
-      parameters = generateParameters(middlewareHandler.target, result.schema);
+      parameters = generateParameters(
+        middlewareHandler.target,
+        result.schema,
+        result.components?.schemas
+      );
     }
     docs.parameters = parameters;
   }
   return { schema: docs, components: result.components };
 }
-function generateParameters(target, schema) {
+function generateParameters(target, schema, schemas) {
   const parameters = [];
-  for (const [key, value] of Object.entries(schema.properties ?? {})) {
+  for (const [key, property] of collectParameterProperties(schema, schemas)) {
     const def = {
       in: target === "param" ? "path" : target,
       name: key,
-      // @ts-expect-error
-      schema: value
+      // @ts-expect-error ParameterObject uses the OpenAPI 3.0 schema type.
+      schema: property.schema
     };
-    const isRequired = schema.required?.includes(key);
-    if (isRequired) {
+    if (property.required) {
       def.required = true;
     }
     if (def.schema && "description" in def.schema && def.schema.description) {
       def.description = def.schema.description;
-      def.schema.description = void 0;
+      def.schema = { ...def.schema, description: void 0 };
     }
     parameters.push(def);
   }
   return parameters;
 }
-async function resolveResponseSchemas(responses) {
-  let components = {};
-  for (const key of Object.keys(responses)) {
-    const response = responses[key];
-    if (!response || !("content" in response)) continue;
-    for (const contentKey of Object.keys(response.content ?? {})) {
-      const raw = response.content?.[contentKey];
-      if (!raw) continue;
-      if (raw.schema && "toOpenAPISchema" in raw.schema) {
-        const result = await raw.schema.toOpenAPISchema();
-        raw.schema = result.schema;
-        if (result.components) {
-          components = mergeComponentsObjects(components, result.components);
+function collectParameterProperties(schema, schemas) {
+  const properties = /* @__PURE__ */ new Map();
+  const resolvingRefs = /* @__PURE__ */ new Set();
+  const collect = (current) => {
+    for (const [key, value] of Object.entries(current.properties ?? {})) {
+      const existing = properties.get(key);
+      properties.set(key, {
+        schema: existing ? { allOf: [existing.schema, value] } : value,
+        required: Boolean(current.required?.includes(key)) || existing?.required
+      });
+    }
+    for (const member of current.allOf ?? []) {
+      if ("$ref" in member) {
+        const prefix = "#/components/schemas/";
+        if (!member.$ref.startsWith(prefix)) continue;
+        const name = member.$ref.slice(prefix.length).replaceAll("~1", "/").replaceAll("~0", "~");
+        const referencedSchema = schemas?.[name];
+        if (referencedSchema && !resolvingRefs.has(name)) {
+          resolvingRefs.add(name);
+          collect(referencedSchema);
+          resolvingRefs.delete(name);
         }
+      } else {
+        collect(member);
       }
     }
+  };
+  collect(schema);
+  return properties;
+}
+async function resolveContentSchemas(content) {
+  let components = {};
+  const resolvedContent = {};
+  for (const [contentKey, raw] of Object.entries(content)) {
+    if (!raw) continue;
+    if (raw.schema && "toOpenAPISchema" in raw.schema) {
+      const result = await raw.schema.toOpenAPISchema();
+      liftSchemaDefs(result);
+      resolvedContent[contentKey] = {
+        ...raw,
+        schema: result.schema
+      };
+      if (result.components) {
+        components = mergeComponentsObjects(components, result.components);
+      }
+    } else {
+      resolvedContent[contentKey] = raw;
+    }
   }
-  return { responses, components };
+  return { content: resolvedContent, components };
+}
+async function resolveResponseSchemas(responses) {
+  let components = {};
+  const resolvedResponses = {};
+  for (const [key, response] of Object.entries(responses)) {
+    if (!response || !("content" in response) || !response.content) {
+      resolvedResponses[key] = response;
+      continue;
+    }
+    const resolved = await resolveContentSchemas(response.content);
+    resolvedResponses[key] = {
+      ...response,
+      content: resolved.content
+    };
+    components = mergeComponentsObjects(components, resolved.components);
+  }
+  return { responses: resolvedResponses, components };
+}
+function liftSchemaDefs(result) {
+  const defs = result.schema.$defs;
+  if (!defs || typeof defs !== "object") return;
+  result.components ??= {};
+  result.components.schemas = {
+    ...defs,
+    ...result.components.schemas
+  };
+  delete result.schema.$defs;
 }
 function mergeComponentsObjects(...components) {
   return components.reduce(
@@ -510,6 +630,10 @@ function injectZodV4DateOverride(schema, userDefined, custom) {
 }
 function validator(target, schema, hook, options) {
   const middleware = standardValidator.sValidator(target, schema, hook);
+  Object.defineProperty(middleware, "name", {
+    value: "validator",
+    configurable: true
+  });
   return Object.assign(middleware, {
     [uniqueSymbol]: {
       target,
@@ -522,6 +646,10 @@ function describeRoute(spec) {
   const middleware = async (_c, next) => {
     await next();
   };
+  Object.defineProperty(middleware, "name", {
+    value: "describeRoute",
+    configurable: true
+  });
   return Object.assign(middleware, {
     [uniqueSymbol]: {
       spec
@@ -563,6 +691,7 @@ function describeResponse(handler, responses, options) {
 }
 
 exports.ALLOWED_METHODS = ALLOWED_METHODS;
+exports.VALIDATION_MARKER = VALIDATION_MARKER;
 exports.clearSpecsContext = clearSpecsContext;
 exports.describeResponse = describeResponse;
 exports.describeRoute = describeRoute;

package/dist/index.d.cts

@@ -5,67 +5,12 @@ import { TypedResponse, RouterRoute, ValidationTargets as ValidationTargets$1, B
 import { loadVendor as loadVendor$2, ToOpenAPISchemaContext } from '@standard-community/standard-openapi';
 import { Hook } from '@hono/standard-validator';
 import { loadVendor as loadVendor$1 } from '@standard-community/standard-json';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 import { StatusCode } from 'hono/utils/http-status';
 import { JSONParsed } from 'hono/utils/types';
+import { InferInput } from 'hono/validator';
 import { JSONSchema7 } from 'json-schema';
 
-/** The Standard Schema interface. */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-    /** The Standard Schema properties. */
-    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
-}
-declare namespace StandardSchemaV1 {
-    /** The Standard Schema properties interface. */
-    export interface Props<Input = unknown, Output = Input> {
-        /** The version number of the standard. */
-        readonly version: 1;
-        /** The vendor name of the schema library. */
-        readonly vendor: string;
-        /** Validates unknown input values. */
-        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        /** Inferred types associated with the schema. */
-        readonly types?: Types<Input, Output> | undefined;
-    }
-    /** The result interface of the validate function. */
-    export type Result<Output> = SuccessResult<Output> | FailureResult;
-    /** The result interface if validation succeeds. */
-    export interface SuccessResult<Output> {
-        /** The typed output value. */
-        readonly value: Output;
-        /** The non-existent issues. */
-        readonly issues?: undefined;
-    }
-    /** The result interface if validation fails. */
-    export interface FailureResult {
-        /** The issues of failed validation. */
-        readonly issues: ReadonlyArray<Issue>;
-    }
-    /** The issue interface of the failure output. */
-    export interface Issue {
-        /** The error message of the issue. */
-        readonly message: string;
-        /** The path of the issue, if any. */
-        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-    }
-    /** The path segment interface of the issue. */
-    export interface PathSegment {
-        /** The key representing a path segment. */
-        readonly key: PropertyKey;
-    }
-    /** The Standard Schema types interface. */
-    export interface Types<Input = unknown, Output = Input> {
-        /** The input type of the schema. */
-        readonly input: Input;
-        /** The output type of the schema. */
-        readonly output: Output;
-    }
-    /** Infers the input type of a Standard Schema. */
-    export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
-    /** Infers the output type of a Standard Schema. */
-    export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
-    export {  };
-}
-
 declare function loadVendor(vendor: string, fn: {
     toJSONSchema?: Parameters<typeof loadVendor$1>[1];
     toOpenAPISchema?: Parameters<typeof loadVendor$2>[1];
@@ -94,13 +39,9 @@ type HasUndefined<T> = undefined extends T ? true : false;
  */
 declare function validator<Schema extends StandardSchemaV1, Target extends keyof ValidationTargets, E extends Env, P extends string, In = StandardSchemaV1.InferInput<Schema>, Out = StandardSchemaV1.InferOutput<Schema>, I extends Input = {
     in: HasUndefined<In> extends true ? {
-        [K in Target]?: In extends ValidationTargets[K] ? In : {
-            [K2 in keyof In]?: ValidationTargets[K][K2];
-        };
+        [K in Target]?: [In] extends [ValidationTargets[K]] ? In : InferInput<In, K>;
     } : {
-        [K in Target]: In extends ValidationTargets[K] ? In : {
-            [K2 in keyof In]: ValidationTargets[K][K2];
-        };
+        [K in Target]: [In] extends [ValidationTargets[K]] ? In : InferInput<In, K>;
     };
     out: {
         [K in Target]: Out;
@@ -132,6 +73,14 @@ declare function describeResponse<E extends Env, P extends string, I extends Inp
  * The unique symbol for the middlewares, which makes it easier to identify them. Not meant to be used directly, unless you're creating a custom middleware.
  */
 declare const uniqueSymbol: unique symbol;
+/**
+ * Internal marker key set on an operation's spec when it is produced by a
+ * `validator()` middleware. It is used to decide whether to auto-inject the
+ * default 400 validation error response, and is stripped from the operation
+ * before the spec is emitted. Must be an enumerable string key so it survives
+ * the `Object.entries`-based merge in `mergeSpecs`.
+ */
+declare const VALIDATION_MARKER = "__HonoOpenAPIValidator__";
 declare const ALLOWED_METHODS: readonly ["GET", "PUT", "POST", "DELETE", "OPTIONS", "HEAD", "PATCH", "TRACE"];
 type AllowedMethods = (typeof ALLOWED_METHODS)[number];
 declare function clearSpecsContext(): void;
@@ -158,13 +107,17 @@ type HandlerUniqueProperty = (ResolverReturnType & {
 type MediaTypeObjectWithResolver = Omit<OpenAPIV3_1.MediaTypeObject, "schema"> & {
     schema?: OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SchemaObject | ResolverReturnType;
 };
+type ContentWithResolver = {
+    [media: string]: MediaTypeObjectWithResolver;
+};
 /**
  * A response object that accepts resolver() output in schema positions.
  */
 type ResponseObjectWithResolver = (Omit<OpenAPIV3_1.ResponseObject, "content"> & {
-    content?: {
-        [media: string]: MediaTypeObjectWithResolver;
-    };
+    content?: ContentWithResolver;
+}) | OpenAPIV3_1.ReferenceObject;
+type RequestBodyObjectWithResolver = (Omit<OpenAPIV3_1.RequestBodyObject, "content"> & {
+    content: ContentWithResolver;
 }) | OpenAPIV3_1.ReferenceObject;
 /**
  * A responses map that accepts resolver() output in schema positions.
@@ -217,10 +170,23 @@ type GenerateSpecOptions = {
      * Default options for `describeRoute` method
      */
     defaultOptions: Partial<Record<AllowedMethods | "ALL", DescribeRouteOptions>>;
+    /**
+     * Automatically include a 400 validation error response for routes
+     * that use `validator()`. Set to `false` to disable, `true` to use
+     * the built-in schema, or provide a custom `ResponseObject`.
+     *
+     * @default true
+     */
+    defaultValidationErrorResponse: boolean | OpenAPIV3_1.ResponseObject;
 };
 type OperationId = string | ((route: RouterRoute) => string);
-type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "responses" | "operationId"> & {
+type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "requestBody" | "responses" | "operationId"> & {
     operationId?: OperationId;
+    /**
+     * Request body metadata. `resolver()` values are converted to OpenAPI
+     * schemas while generating the document.
+     */
+    requestBody?: RequestBodyObjectWithResolver;
     /**
      * Pass `true` to hide route from OpenAPI/swagger document
      */
@@ -241,11 +207,12 @@ type RegisterSchemaPathOptions = {
     };
     paths: Partial<OpenAPIV3_1.PathsObject>;
 };
-type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags";
+type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags" | "defaultValidationErrorResponse";
 type SanitizedGenerateSpecOptions = Pick<GenerateSpecOptions, HaveDefaultValues> & Omit<Partial<GenerateSpecOptions>, HaveDefaultValues>;
 type SpecContext = {
     components: OpenAPIV3_1.ComponentsObject;
     options: SanitizedGenerateSpecOptions;
+    validationErrorResponse?: OpenAPIV3_1.ResponseObject;
 };
 
 /**
@@ -298,4 +265,4 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
     jsonSchemaDialect?: string;
 }>;
 
-export { ALLOWED_METHODS, type AllowedMethods, type DescribeRouteOptions, type GenerateSpecOptions, type HandlerUniqueProperty, type PromiseOr, type RegisterSchemaPathOptions, type ResolverReturnType, type ResponsesWithResolver, type SpecContext, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };
+export { ALLOWED_METHODS, type AllowedMethods, type ContentWithResolver, type DescribeRouteOptions, type GenerateSpecOptions, type HandlerUniqueProperty, type PromiseOr, type RegisterSchemaPathOptions, type ResolverReturnType, type ResponsesWithResolver, type SpecContext, VALIDATION_MARKER, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/dist/index.d.ts

@@ -5,67 +5,12 @@ import { TypedResponse, RouterRoute, ValidationTargets as ValidationTargets$1, B
 import { loadVendor as loadVendor$2, ToOpenAPISchemaContext } from '@standard-community/standard-openapi';
 import { Hook } from '@hono/standard-validator';
 import { loadVendor as loadVendor$1 } from '@standard-community/standard-json';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 import { StatusCode } from 'hono/utils/http-status';
 import { JSONParsed } from 'hono/utils/types';
+import { InferInput } from 'hono/validator';
 import { JSONSchema7 } from 'json-schema';
 
-/** The Standard Schema interface. */
-interface StandardSchemaV1<Input = unknown, Output = Input> {
-    /** The Standard Schema properties. */
-    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
-}
-declare namespace StandardSchemaV1 {
-    /** The Standard Schema properties interface. */
-    export interface Props<Input = unknown, Output = Input> {
-        /** The version number of the standard. */
-        readonly version: 1;
-        /** The vendor name of the schema library. */
-        readonly vendor: string;
-        /** Validates unknown input values. */
-        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        /** Inferred types associated with the schema. */
-        readonly types?: Types<Input, Output> | undefined;
-    }
-    /** The result interface of the validate function. */
-    export type Result<Output> = SuccessResult<Output> | FailureResult;
-    /** The result interface if validation succeeds. */
-    export interface SuccessResult<Output> {
-        /** The typed output value. */
-        readonly value: Output;
-        /** The non-existent issues. */
-        readonly issues?: undefined;
-    }
-    /** The result interface if validation fails. */
-    export interface FailureResult {
-        /** The issues of failed validation. */
-        readonly issues: ReadonlyArray<Issue>;
-    }
-    /** The issue interface of the failure output. */
-    export interface Issue {
-        /** The error message of the issue. */
-        readonly message: string;
-        /** The path of the issue, if any. */
-        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-    }
-    /** The path segment interface of the issue. */
-    export interface PathSegment {
-        /** The key representing a path segment. */
-        readonly key: PropertyKey;
-    }
-    /** The Standard Schema types interface. */
-    export interface Types<Input = unknown, Output = Input> {
-        /** The input type of the schema. */
-        readonly input: Input;
-        /** The output type of the schema. */
-        readonly output: Output;
-    }
-    /** Infers the input type of a Standard Schema. */
-    export type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
-    /** Infers the output type of a Standard Schema. */
-    export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
-    export {  };
-}
-
 declare function loadVendor(vendor: string, fn: {
     toJSONSchema?: Parameters<typeof loadVendor$1>[1];
     toOpenAPISchema?: Parameters<typeof loadVendor$2>[1];
@@ -94,13 +39,9 @@ type HasUndefined<T> = undefined extends T ? true : false;
  */
 declare function validator<Schema extends StandardSchemaV1, Target extends keyof ValidationTargets, E extends Env, P extends string, In = StandardSchemaV1.InferInput<Schema>, Out = StandardSchemaV1.InferOutput<Schema>, I extends Input = {
     in: HasUndefined<In> extends true ? {
-        [K in Target]?: In extends ValidationTargets[K] ? In : {
-            [K2 in keyof In]?: ValidationTargets[K][K2];
-        };
+        [K in Target]?: [In] extends [ValidationTargets[K]] ? In : InferInput<In, K>;
     } : {
-        [K in Target]: In extends ValidationTargets[K] ? In : {
-            [K2 in keyof In]: ValidationTargets[K][K2];
-        };
+        [K in Target]: [In] extends [ValidationTargets[K]] ? In : InferInput<In, K>;
     };
     out: {
         [K in Target]: Out;
@@ -132,6 +73,14 @@ declare function describeResponse<E extends Env, P extends string, I extends Inp
  * The unique symbol for the middlewares, which makes it easier to identify them. Not meant to be used directly, unless you're creating a custom middleware.
  */
 declare const uniqueSymbol: unique symbol;
+/**
+ * Internal marker key set on an operation's spec when it is produced by a
+ * `validator()` middleware. It is used to decide whether to auto-inject the
+ * default 400 validation error response, and is stripped from the operation
+ * before the spec is emitted. Must be an enumerable string key so it survives
+ * the `Object.entries`-based merge in `mergeSpecs`.
+ */
+declare const VALIDATION_MARKER = "__HonoOpenAPIValidator__";
 declare const ALLOWED_METHODS: readonly ["GET", "PUT", "POST", "DELETE", "OPTIONS", "HEAD", "PATCH", "TRACE"];
 type AllowedMethods = (typeof ALLOWED_METHODS)[number];
 declare function clearSpecsContext(): void;
@@ -158,13 +107,17 @@ type HandlerUniqueProperty = (ResolverReturnType & {
 type MediaTypeObjectWithResolver = Omit<OpenAPIV3_1.MediaTypeObject, "schema"> & {
     schema?: OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SchemaObject | ResolverReturnType;
 };
+type ContentWithResolver = {
+    [media: string]: MediaTypeObjectWithResolver;
+};
 /**
  * A response object that accepts resolver() output in schema positions.
  */
 type ResponseObjectWithResolver = (Omit<OpenAPIV3_1.ResponseObject, "content"> & {
-    content?: {
-        [media: string]: MediaTypeObjectWithResolver;
-    };
+    content?: ContentWithResolver;
+}) | OpenAPIV3_1.ReferenceObject;
+type RequestBodyObjectWithResolver = (Omit<OpenAPIV3_1.RequestBodyObject, "content"> & {
+    content: ContentWithResolver;
 }) | OpenAPIV3_1.ReferenceObject;
 /**
  * A responses map that accepts resolver() output in schema positions.
@@ -217,10 +170,23 @@ type GenerateSpecOptions = {
      * Default options for `describeRoute` method
      */
     defaultOptions: Partial<Record<AllowedMethods | "ALL", DescribeRouteOptions>>;
+    /**
+     * Automatically include a 400 validation error response for routes
+     * that use `validator()`. Set to `false` to disable, `true` to use
+     * the built-in schema, or provide a custom `ResponseObject`.
+     *
+     * @default true
+     */
+    defaultValidationErrorResponse: boolean | OpenAPIV3_1.ResponseObject;
 };
 type OperationId = string | ((route: RouterRoute) => string);
-type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "responses" | "operationId"> & {
+type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "requestBody" | "responses" | "operationId"> & {
     operationId?: OperationId;
+    /**
+     * Request body metadata. `resolver()` values are converted to OpenAPI
+     * schemas while generating the document.
+     */
+    requestBody?: RequestBodyObjectWithResolver;
     /**
      * Pass `true` to hide route from OpenAPI/swagger document
      */
@@ -241,11 +207,12 @@ type RegisterSchemaPathOptions = {
     };
     paths: Partial<OpenAPIV3_1.PathsObject>;
 };
-type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags";
+type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags" | "defaultValidationErrorResponse";
 type SanitizedGenerateSpecOptions = Pick<GenerateSpecOptions, HaveDefaultValues> & Omit<Partial<GenerateSpecOptions>, HaveDefaultValues>;
 type SpecContext = {
     components: OpenAPIV3_1.ComponentsObject;
     options: SanitizedGenerateSpecOptions;
+    validationErrorResponse?: OpenAPIV3_1.ResponseObject;
 };
 
 /**
@@ -298,4 +265,4 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
     jsonSchemaDialect?: string;
 }>;
 
-export { ALLOWED_METHODS, type AllowedMethods, type DescribeRouteOptions, type GenerateSpecOptions, type HandlerUniqueProperty, type PromiseOr, type RegisterSchemaPathOptions, type ResolverReturnType, type ResponsesWithResolver, type SpecContext, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };
+export { ALLOWED_METHODS, type AllowedMethods, type ContentWithResolver, type DescribeRouteOptions, type GenerateSpecOptions, type HandlerUniqueProperty, type PromiseOr, type RegisterSchemaPathOptions, type ResolverReturnType, type ResponsesWithResolver, type SpecContext, VALIDATION_MARKER, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/dist/index.js

@@ -4,6 +4,7 @@ import { loadVendor as loadVendor$1, toJsonSchema } from '@standard-community/st
 import { loadVendor as loadVendor$2, toOpenAPISchema } from '@standard-community/standard-openapi';
 
 const uniqueSymbol = Symbol("openapi");
+const VALIDATION_MARKER = "__HonoOpenAPIValidator__";
 const ALLOWED_METHODS = [
   "GET",
   "PUT",
@@ -56,7 +57,9 @@ const specsByPathContext = /* @__PURE__ */ new Map();
 function getPathContext(path) {
   const context = [];
   for (const [key, data] of specsByPathContext) {
-    if (data && path.match(key)) {
+    if (!data) continue;
+    const prefix = key.endsWith("/*") ? key.slice(0, -2) : key;
+    if (path === prefix || path.startsWith(`${prefix}/`)) {
       context.push(data);
     }
   }
@@ -157,6 +160,8 @@ function removeExcludedPaths(paths, ctx) {
     for (const method of Object.keys(value)) {
       const schema = value[method];
       if (schema == null) continue;
+      const hasValidation = schema[VALIDATION_MARKER] === true;
+      delete schema[VALIDATION_MARKER];
       if (key.includes("{")) {
         schema.parameters = schema.parameters ? [...schema.parameters] : [];
         const pathParameters = key.split("/").filter(
@@ -196,6 +201,16 @@ function removeExcludedPaths(paths, ctx) {
           200: {}
         };
       }
+      if (hasValidation && ctx.options.defaultValidationErrorResponse !== false && !schema.responses["400"]) {
+        const errorResponse = ctx.options.defaultValidationErrorResponse;
+        if (typeof errorResponse === "object") {
+          schema.responses["400"] = structuredClone(errorResponse);
+        } else if (ctx.validationErrorResponse) {
+          schema.responses["400"] = structuredClone(
+            ctx.validationErrorResponse
+          );
+        }
+      }
     }
     const filteredValue = {};
     for (const method of Object.keys(value)) {
@@ -215,7 +230,27 @@ const DEFAULT_OPTIONS = {
   excludeStaticFile: true,
   exclude: [],
   excludeMethods: ["OPTIONS"],
-  excludeTags: []
+  excludeTags: [],
+  defaultValidationErrorResponse: true
+};
+const DEFAULT_VALIDATION_ERROR = {
+  description: "Validation Error",
+  content: {
+    "application/json": {
+      schema: {
+        type: "object",
+        properties: {
+          success: { type: "boolean", enum: [false] },
+          error: {
+            type: "array",
+            items: {}
+          },
+          data: {}
+        },
+        required: ["success", "error", "data"]
+      }
+    }
+  }
 };
 function openAPIRouteHandler(hono, options) {
   let specs;
@@ -232,9 +267,14 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     options: {
       ...DEFAULT_OPTIONS,
       ...options
-    }
+    },
+    validationErrorResponse: DEFAULT_VALIDATION_ERROR
   };
   const _documentation = ctx.options.documentation ?? {};
+  const documentation = {
+    ..._documentation,
+    components: _documentation.components && { ..._documentation.components }
+  };
   clearSpecsContext();
   const paths = await generatePaths(hono, ctx);
   for (const path in paths) {
@@ -250,27 +290,30 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       }
     }
   }
-  const { components: resolvedDocComponents } = _documentation.components?.responses ? await resolveResponseSchemas(_documentation.components.responses) : { components: {} };
+  const resolvedDocumentation = documentation.components?.responses ? await resolveResponseSchemas(documentation.components.responses) : void 0;
+  if (resolvedDocumentation && documentation.components) {
+    documentation.components.responses = resolvedDocumentation.responses;
+  }
   const components = mergeComponentsObjects(
-    _documentation.components,
-    resolvedDocComponents,
+    documentation.components,
+    resolvedDocumentation?.components,
     ctx.components
   );
   return {
     openapi: "3.1.0",
-    ..._documentation,
-    tags: _documentation.tags?.filter(
+    ...documentation,
+    tags: documentation.tags?.filter(
       (tag) => !ctx.options.excludeTags?.includes(tag?.name)
     ),
     info: {
       title: "Hono Documentation",
       description: "Development documentation",
       version: "0.0.0",
-      ..._documentation.info
+      ...documentation.info
     },
     paths: {
       ...removeExcludedPaths(paths, ctx),
-      ..._documentation.paths
+      ...documentation.paths
     },
     components
   };
@@ -336,12 +379,27 @@ async function getSpec(middlewareHandler, defaultOptions) {
     let components = {};
     if (tmp.responses) {
       const resolved = await resolveResponseSchemas(tmp.responses);
+      tmp.responses = resolved.responses;
       components = resolved.components;
     }
+    if (tmp.requestBody && "content" in tmp.requestBody) {
+      const resolved = await resolveContentSchemas(tmp.requestBody.content);
+      tmp.requestBody = {
+        ...tmp.requestBody,
+        content: resolved.content
+      };
+      components = mergeComponentsObjects(components, resolved.components);
+    }
     return { schema: tmp, components };
   }
   const result = await middlewareHandler.toOpenAPISchema();
-  const docs = { ...defaultOptions };
+  liftSchemaDefs(result);
+  const docs = {
+    ...defaultOptions,
+    // Mark this operation as validator-derived so a default 400 validation
+    // error response can be auto-injected later (see removeExcludedPaths).
+    [VALIDATION_MARKER]: true
+  };
   if (middlewareHandler.target === "form" || middlewareHandler.target === "json") {
     const media = middlewareHandler.options?.media ?? middlewareHandler.target === "json" ? "application/json" : "multipart/form-data";
     if (!docs.requestBody || !("content" in docs.requestBody) || !docs.requestBody.content) {
@@ -379,51 +437,113 @@ async function getSpec(middlewareHandler, defaultOptions) {
         });
       }
     } else {
-      parameters = generateParameters(middlewareHandler.target, result.schema);
+      parameters = generateParameters(
+        middlewareHandler.target,
+        result.schema,
+        result.components?.schemas
+      );
     }
     docs.parameters = parameters;
   }
   return { schema: docs, components: result.components };
 }
-function generateParameters(target, schema) {
+function generateParameters(target, schema, schemas) {
   const parameters = [];
-  for (const [key, value] of Object.entries(schema.properties ?? {})) {
+  for (const [key, property] of collectParameterProperties(schema, schemas)) {
     const def = {
       in: target === "param" ? "path" : target,
       name: key,
-      // @ts-expect-error
-      schema: value
+      // @ts-expect-error ParameterObject uses the OpenAPI 3.0 schema type.
+      schema: property.schema
     };
-    const isRequired = schema.required?.includes(key);
-    if (isRequired) {
+    if (property.required) {
       def.required = true;
     }
     if (def.schema && "description" in def.schema && def.schema.description) {
       def.description = def.schema.description;
-      def.schema.description = void 0;
+      def.schema = { ...def.schema, description: void 0 };
     }
     parameters.push(def);
   }
   return parameters;
 }
-async function resolveResponseSchemas(responses) {
-  let components = {};
-  for (const key of Object.keys(responses)) {
-    const response = responses[key];
-    if (!response || !("content" in response)) continue;
-    for (const contentKey of Object.keys(response.content ?? {})) {
-      const raw = response.content?.[contentKey];
-      if (!raw) continue;
-      if (raw.schema && "toOpenAPISchema" in raw.schema) {
-        const result = await raw.schema.toOpenAPISchema();
-        raw.schema = result.schema;
-        if (result.components) {
-          components = mergeComponentsObjects(components, result.components);
+function collectParameterProperties(schema, schemas) {
+  const properties = /* @__PURE__ */ new Map();
+  const resolvingRefs = /* @__PURE__ */ new Set();
+  const collect = (current) => {
+    for (const [key, value] of Object.entries(current.properties ?? {})) {
+      const existing = properties.get(key);
+      properties.set(key, {
+        schema: existing ? { allOf: [existing.schema, value] } : value,
+        required: Boolean(current.required?.includes(key)) || existing?.required
+      });
+    }
+    for (const member of current.allOf ?? []) {
+      if ("$ref" in member) {
+        const prefix = "#/components/schemas/";
+        if (!member.$ref.startsWith(prefix)) continue;
+        const name = member.$ref.slice(prefix.length).replaceAll("~1", "/").replaceAll("~0", "~");
+        const referencedSchema = schemas?.[name];
+        if (referencedSchema && !resolvingRefs.has(name)) {
+          resolvingRefs.add(name);
+          collect(referencedSchema);
+          resolvingRefs.delete(name);
         }
+      } else {
+        collect(member);
       }
     }
+  };
+  collect(schema);
+  return properties;
+}
+async function resolveContentSchemas(content) {
+  let components = {};
+  const resolvedContent = {};
+  for (const [contentKey, raw] of Object.entries(content)) {
+    if (!raw) continue;
+    if (raw.schema && "toOpenAPISchema" in raw.schema) {
+      const result = await raw.schema.toOpenAPISchema();
+      liftSchemaDefs(result);
+      resolvedContent[contentKey] = {
+        ...raw,
+        schema: result.schema
+      };
+      if (result.components) {
+        components = mergeComponentsObjects(components, result.components);
+      }
+    } else {
+      resolvedContent[contentKey] = raw;
+    }
   }
-  return { responses, components };
+  return { content: resolvedContent, components };
+}
+async function resolveResponseSchemas(responses) {
+  let components = {};
+  const resolvedResponses = {};
+  for (const [key, response] of Object.entries(responses)) {
+    if (!response || !("content" in response) || !response.content) {
+      resolvedResponses[key] = response;
+      continue;
+    }
+    const resolved = await resolveContentSchemas(response.content);
+    resolvedResponses[key] = {
+      ...response,
+      content: resolved.content
+    };
+    components = mergeComponentsObjects(components, resolved.components);
+  }
+  return { responses: resolvedResponses, components };
+}
+function liftSchemaDefs(result) {
+  const defs = result.schema.$defs;
+  if (!defs || typeof defs !== "object") return;
+  result.components ??= {};
+  result.components.schemas = {
+    ...defs,
+    ...result.components.schemas
+  };
+  delete result.schema.$defs;
 }
 function mergeComponentsObjects(...components) {
   return components.reduce(
@@ -508,6 +628,10 @@ function injectZodV4DateOverride(schema, userDefined, custom) {
 }
 function validator(target, schema, hook, options) {
   const middleware = sValidator(target, schema, hook);
+  Object.defineProperty(middleware, "name", {
+    value: "validator",
+    configurable: true
+  });
   return Object.assign(middleware, {
     [uniqueSymbol]: {
       target,
@@ -520,6 +644,10 @@ function describeRoute(spec) {
   const middleware = async (_c, next) => {
     await next();
   };
+  Object.defineProperty(middleware, "name", {
+    value: "describeRoute",
+    configurable: true
+  });
   return Object.assign(middleware, {
     [uniqueSymbol]: {
       spec
@@ -560,4 +688,4 @@ function describeResponse(handler, responses, options) {
   });
 }
 
-export { ALLOWED_METHODS, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };
+export { ALLOWED_METHODS, VALIDATION_MARKER, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/package.json

@@ -1,86 +1,78 @@
-{
-  "name": "hono-openapi",
-  "description": "OpenAPI schema generator for Hono",
-  "version": "1.3.0",
-  "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "license": "MIT",
-  "scripts": {
-    "build": "pkgroll --clean-dist",
-    "lint": "biome check .",
-    "format": "biome check --write .",
-    "prepare": "is-ci || husky",
-    "test": "vitest"
-  },
-  "keywords": [
-    "hono",
-    "openapi",
-    "zod",
-    "valibot",
-    "typebox",
-    "arktype",
-    "effect"
-  ],
-  "homepage": "https://github.com/rhinobase/hono-openapi",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/rhinobase/hono-openapi.git"
-  },
-  "bugs": {
-    "url": "https://github.com/rhinobase/hono-openapi/issues"
-  },
-  "exports": {
-    "import": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "require": {
-      "types": "./dist/index.d.cts",
-      "default": "./dist/index.cjs"
-    }
-  },
-  "peerDependencies": {
-    "@hono/standard-validator": "^0.2.0",
-    "@standard-community/standard-json": "^0.3.5",
-    "@standard-community/standard-openapi": "^0.2.9",
-    "@types/json-schema": "^7.0.15",
-    "hono": "^4.8.3",
-    "openapi-types": "^12.1.3"
-  },
-  "peerDependenciesMeta": {
-    "@hono/standard-validator": {
-      "optional": true
-    },
-    "hono": {
-      "optional": true
-    }
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.0.6",
-    "@standard-schema/spec": "^1.0.0",
-    "@valibot/to-json-schema": "^1.3.0",
-    "arktype": "^2.1.22",
-    "effect": "^3.17.13",
-    "husky": "^9.1.7",
-    "is-ci": "^4.1.0",
-    "nano-staged": "^0.8.0",
-    "pkg-pr-new": "^0.0.60",
-    "pkgroll": "^2.13.1",
-    "typebox": "^1.0.17",
-    "typescript": "^5.8.3",
-    "sury": "^10.0.0",
-    "valibot": "^1.1.0",
-    "vitest": "^3.2.4",
-    "zod": "^3.23.8",
-    "zod-openapi": "^4"
-  },
-  "packageManager": "pnpm@10.0.0"
-}
+{
+  "name": "hono-openapi",
+  "description": "OpenAPI schema generator for Hono",
+  "version": "1.3.2",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "hono",
+    "openapi",
+    "zod",
+    "valibot",
+    "typebox",
+    "arktype",
+    "effect"
+  ],
+  "homepage": "https://github.com/rhinobase/hono-openapi",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhinobase/hono-openapi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rhinobase/hono-openapi/issues"
+  },
+  "exports": {
+    "import": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "require": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@hono/standard-validator": "^0.4.0",
+    "@standard-community/standard-json": "^0.3.5",
+    "@standard-community/standard-openapi": "^0.2.9",
+    "@standard-schema/spec": "^1.0.0",
+    "@types/json-schema": "^7.0.15",
+    "openapi-types": "^12.1.3"
+  },
+  "peerDependencies": {
+    "hono": "^4.11.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.6",
+    "@valibot/to-json-schema": "^1.3.0",
+    "arktype": "^2.1.22",
+    "effect": "^3.17.14",
+    "husky": "^9.1.7",
+    "is-ci": "^4.1.0",
+    "nano-staged": "^0.8.0",
+    "pkg-pr-new": "^0.0.60",
+    "pkgroll": "^2.13.1",
+    "typebox": "^1.0.17",
+    "typescript": "^5.8.3",
+    "sury": "^10.0.0",
+    "valibot": "^1.1.0",
+    "vitest": "^3.2.4",
+    "zod": "^3.23.8",
+    "zod-openapi": "^4"
+  },
+  "scripts": {
+    "build": "pkgroll --clean-dist",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest"
+  }
+}