hono-openapi 1.3.2 → 1.3.4

package/dist/index.cjs

@@ -55,10 +55,13 @@ function mergeParameters(...params) {
   }, /* @__PURE__ */ new Map());
   return Array.from(merged.values());
 }
+const specComponents = /* @__PURE__ */ new WeakMap();
+const setSpecComponents = (spec, components) => specComponents.set(spec, components);
+const getSpecComponents = (spec) => spec != null && typeof spec === "object" && specComponents.get(spec) || [];
 const specsByPathContext = /* @__PURE__ */ new Map();
-function getPathContext(path) {
+function getPathContext(path, pathContext) {
   const context = [];
-  for (const [key, data] of specsByPathContext) {
+  for (const [key, data] of pathContext) {
     if (!data) continue;
     const prefix = key.endsWith("/*") ? key.slice(0, -2) : key;
     if (path === prefix || path.startsWith(`${prefix}/`)) {
@@ -70,8 +73,21 @@ function getPathContext(path) {
 function clearSpecsContext() {
   specsByPathContext.clear();
 }
+function mergeRequestBodies(previous, current) {
+  if (!previous || !current || "$ref" in previous || "$ref" in current) {
+    return current;
+  }
+  return {
+    ...previous,
+    ...current,
+    content: {
+      ...previous.content,
+      ...current.content
+    }
+  };
+}
 function mergeSpecs(route, ...specs) {
-  return specs.reduce(
+  const merged = specs.reduce(
     (prev, spec) => {
       if (!spec || !prev) return prev;
       for (const [key, value] of Object.entries(spec)) {
@@ -91,6 +107,11 @@ function mergeSpecs(route, ...specs) {
           } else {
             if (key === "parameters") {
               prev[key] = mergeParameters(prev[key], value);
+            } else if (key === "requestBody") {
+              prev.requestBody = mergeRequestBodies(
+                prev.requestBody,
+                value
+              );
             } else {
               prev[key] = {
                 ...prev[key],
@@ -108,31 +129,29 @@ function mergeSpecs(route, ...specs) {
       operationId: generateOperationId(route)
     }
   );
+  setSpecComponents(merged, specs.flatMap(getSpecComponents));
+  return merged;
 }
-function registerSchemaPath({
-  route,
-  specs,
-  paths
-}) {
+function registerSchemaPath({ route, specs, paths }, pathContext = specsByPathContext) {
   const path = toOpenAPIPath(route.path);
   const method = route.method.toLowerCase();
   if (method === "all") {
     if (!specs) return;
-    if (specsByPathContext.has(path)) {
-      const prev = specsByPathContext.get(path) ?? {};
-      specsByPathContext.set(path, mergeSpecs(route, prev, specs));
+    if (pathContext.has(path)) {
+      const prev = pathContext.get(path) ?? {};
+      pathContext.set(path, mergeSpecs(route, prev, specs));
     } else {
-      specsByPathContext.set(path, specs);
+      pathContext.set(path, specs);
     }
   } else {
-    const pathContext = getPathContext(path);
+    const context = getPathContext(path, pathContext);
     if (!(path in paths)) {
       paths[path] = {};
     }
     if (paths[path]) {
       paths[path][method] = mergeSpecs(
         route,
-        ...pathContext,
+        ...context,
         paths[path]?.[method],
         specs
       );
@@ -226,6 +245,52 @@ function removeExcludedPaths(paths, ctx) {
   }
   return newPaths;
 }
+const COMPONENTS_PREFIX = "#/components/";
+const componentKey = (type, name) => `${type}/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+const componentRefs = (value) => {
+  if (Array.isArray(value)) {
+    return value.flatMap(componentRefs);
+  }
+  if (value == null || typeof value !== "object") {
+    return [];
+  }
+  return Object.entries(value).flatMap(([key, item]) => {
+    if (key !== "$ref" || typeof item !== "string") {
+      return componentRefs(item);
+    }
+    return item.startsWith(COMPONENTS_PREFIX) ? [item.slice(COMPONENTS_PREFIX.length)] : [];
+  });
+};
+const reachableRefs = (refs, components, reached) => refs.reduce((seen, ref) => {
+  if (seen.has(ref)) {
+    return seen;
+  }
+  const [type, ...name] = ref.split("/");
+  const component = components[type]?.[name.join("/").replaceAll("~1", "/").replaceAll("~0", "~")];
+  return reachableRefs(componentRefs(component), components, seen.add(ref));
+}, reached);
+function documentedComponents(components, paths, documentation) {
+  const contributed = new Set(
+    Object.values(paths).flatMap((item) => item == null ? [] : Object.values(item)).flatMap(getSpecComponents).flatMap(
+      (operationComponents) => Object.entries(operationComponents).flatMap(
+        ([type, entries]) => Object.keys(entries ?? {}).map((name) => componentKey(type, name))
+      )
+    )
+  );
+  const kept = reachableRefs(
+    componentRefs(documentation),
+    components,
+    contributed
+  );
+  return Object.fromEntries(
+    Object.entries(components).flatMap(([type, entries]) => {
+      const remaining = Object.entries(entries ?? {}).filter(
+        ([name]) => kept.has(componentKey(type, name))
+      );
+      return remaining.length > 0 ? [[type, Object.fromEntries(remaining)]] : [];
+    })
+  );
+}
 
 const DEFAULT_OPTIONS = {
   documentation: {},
@@ -277,7 +342,6 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     ..._documentation,
     components: _documentation.components && { ..._documentation.components }
   };
-  clearSpecsContext();
   const paths = await generatePaths(hono, ctx);
   for (const path in paths) {
     for (const method in paths[path]) {
@@ -296,10 +360,14 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
   if (resolvedDocumentation && documentation.components) {
     documentation.components.responses = resolvedDocumentation.responses;
   }
+  const documentedPaths = removeExcludedPaths(paths, ctx);
   const components = mergeComponentsObjects(
     documentation.components,
     resolvedDocumentation?.components,
-    ctx.components
+    documentedComponents(ctx.components, documentedPaths, [
+      documentation,
+      resolvedDocumentation?.components
+    ])
   );
   return {
     openapi: "3.1.0",
@@ -314,7 +382,7 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       ...documentation.info
     },
     paths: {
-      ...removeExcludedPaths(paths, ctx),
+      ...documentedPaths,
       ...documentation.paths
     },
     components
@@ -322,14 +390,18 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
 }
 async function generatePaths(hono, ctx) {
   const paths = {};
+  const pathContext = /* @__PURE__ */ new Map();
   for (const route of hono.routes) {
     const middlewareHandler = handler.findTargetHandler(route.handler)[uniqueSymbol];
     if (!middlewareHandler) {
       if (ctx.options.includeEmptyPaths) {
-        registerSchemaPath({
-          route,
-          paths
-        });
+        registerSchemaPath(
+          {
+            route,
+            paths
+          },
+          pathContext
+        );
       }
       continue;
     }
@@ -345,14 +417,19 @@ async function generatePaths(hono, ctx) {
     const defaultOptionsForThisMethod = ctx.options.defaultOptions?.[routeMethod] && { ...ctx.options.defaultOptions[routeMethod] };
     const { schema: routeSpecs, components = {} } = await getSpec(
       middlewareHandler,
-      defaultOptionsForThisMethod
+      defaultOptionsForThisMethod,
+      ctx.components.parameters
     );
     ctx.components = mergeComponentsObjects(ctx.components, components);
-    registerSchemaPath({
-      route,
-      specs: routeSpecs,
-      paths
-    });
+    setSpecComponents(routeSpecs, [components]);
+    registerSchemaPath(
+      {
+        route,
+        specs: routeSpecs,
+        paths
+      },
+      pathContext
+    );
   }
   return paths;
 }
@@ -368,7 +445,7 @@ function getHiddenValue(options) {
   }
   return false;
 }
-async function getSpec(middlewareHandler, defaultOptions) {
+async function getSpec(middlewareHandler, defaultOptions, parameterComponents) {
   if ("spec" in middlewareHandler) {
     const tmp = {
       ...defaultOptions,
@@ -403,7 +480,7 @@ async function getSpec(middlewareHandler, defaultOptions) {
     [VALIDATION_MARKER]: true
   };
   if (middlewareHandler.target === "form" || middlewareHandler.target === "json") {
-    const media = middlewareHandler.options?.media ?? middlewareHandler.target === "json" ? "application/json" : "multipart/form-data";
+    const media = middlewareHandler.options?.media ?? (middlewareHandler.target === "json" ? "application/json" : "multipart/form-data");
     if (!docs.requestBody || !("content" in docs.requestBody) || !docs.requestBody.content) {
       docs.requestBody = {
         required: true,
@@ -425,18 +502,21 @@ async function getSpec(middlewareHandler, defaultOptions) {
       const pos = ref.split("/").pop();
       if (pos && result.components?.schemas?.[pos]) {
         const schema = result.components.schemas[pos];
-        const newParameters = generateParameters(
+        const generatedParameters = generateParameters(
           middlewareHandler.target,
-          schema
-        )[0];
-        if (!result.components.parameters) {
-          result.components.parameters = {};
+          schema,
+          result.components.schemas
+        );
+        const singleParameter = generatedParameters.length === 1 ? generatedParameters[0] : void 0;
+        const existingParameter = parameterComponents?.[pos];
+        if (singleParameter && (!existingParameter || "in" in existingParameter && existingParameter.in === singleParameter.in && existingParameter.name === singleParameter.name)) {
+          result.components.parameters ??= {};
+          result.components.parameters[pos] = singleParameter;
+          parameters.push({ $ref: `#/components/parameters/${pos}` });
+          delete result.components.schemas[pos];
+        } else {
+          parameters = generatedParameters;
         }
-        result.components.parameters[pos] = newParameters;
-        delete result.components.schemas[pos];
-        parameters.push({
-          $ref: `#/components/parameters/${pos}`
-        });
       }
     } else {
       parameters = generateParameters(
@@ -695,11 +775,14 @@ exports.VALIDATION_MARKER = VALIDATION_MARKER;
 exports.clearSpecsContext = clearSpecsContext;
 exports.describeResponse = describeResponse;
 exports.describeRoute = describeRoute;
+exports.documentedComponents = documentedComponents;
 exports.generateSpecs = generateSpecs;
+exports.getSpecComponents = getSpecComponents;
 exports.loadVendor = loadVendor;
 exports.openAPIRouteHandler = openAPIRouteHandler;
 exports.registerSchemaPath = registerSchemaPath;
 exports.removeExcludedPaths = removeExcludedPaths;
 exports.resolver = resolver;
+exports.setSpecComponents = setSpecComponents;
 exports.uniqueSymbol = uniqueSymbol;
 exports.validator = validator;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import * as openapi_types from 'openapi-types';
 import { OpenAPIV3_1 } from 'openapi-types';
+import * as hono from 'hono';
 import { Env, Input, Context, Next, MiddlewareHandler, ValidationTargets, Hono } from 'hono';
 import { TypedResponse, RouterRoute, ValidationTargets as ValidationTargets$1, BlankEnv, Input as Input$1, BlankInput, Schema, BlankSchema, MiddlewareHandler as MiddlewareHandler$1 } from 'hono/types';
 import { loadVendor as loadVendor$2, ToOpenAPISchemaContext } from '@standard-community/standard-openapi';
@@ -83,9 +84,34 @@ declare const uniqueSymbol: unique symbol;
 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 const setSpecComponents: (spec: object, components: OpenAPIV3_1.ComponentsObject[]) => WeakMap<object, OpenAPIV3_1.ComponentsObject[]>;
+declare const getSpecComponents: (spec: unknown) => OpenAPIV3_1.ComponentsObject[];
 declare function clearSpecsContext(): void;
-declare function registerSchemaPath({ route, specs, paths, }: RegisterSchemaPathOptions): void;
+declare function registerSchemaPath({ route, specs, paths }: RegisterSchemaPathOptions, pathContext?: Map<string, Omit<OpenAPIV3_1.OperationObject<{}>, "responses" | "operationId" | "requestBody"> & {
+    operationId?: string | ((route: RouterRoute) => string);
+    requestBody?: OpenAPIV3_1.ReferenceObject | (Omit<OpenAPIV3_1.RequestBodyObject, "content"> & {
+        content: ContentWithResolver;
+    });
+    hide?: boolean | ((props: {
+        c?: hono.Context;
+        method: string;
+        path: string;
+    }) => boolean);
+    responses?: ResponsesWithResolver;
+} & {
+    operationId?: string | ((route: RouterRoute) => string);
+}>): void;
 declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: SpecContext): OpenAPIV3_1.PathsObject<{}, {}>;
+/**
+ * Keeps the generated components that the documented operations brought in,
+ * and the ones `documentation` refers to, directly or through other
+ * components.
+ *
+ * Components are collected from every route while the paths are generated,
+ * including routes that are hidden or excluded afterwards. Without this, those
+ * routes would still publish the schemas only they use.
+ */
+declare function documentedComponents(components: OpenAPIV3_1.ComponentsObject, paths: OpenAPIV3_1.PathsObject, documentation: unknown): OpenAPIV3_1.ComponentsObject;
 
 type PromiseOr<T> = T | Promise<T>;
 type ResolverReturnType = ReturnType<typeof resolver> & {
@@ -265,4 +291,4 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
     jsonSchemaDialect?: string;
 }>;
 
-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 };
+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, documentedComponents, generateSpecs, getSpecComponents, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, setSpecComponents, uniqueSymbol, validator };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as openapi_types from 'openapi-types';
 import { OpenAPIV3_1 } from 'openapi-types';
+import * as hono from 'hono';
 import { Env, Input, Context, Next, MiddlewareHandler, ValidationTargets, Hono } from 'hono';
 import { TypedResponse, RouterRoute, ValidationTargets as ValidationTargets$1, BlankEnv, Input as Input$1, BlankInput, Schema, BlankSchema, MiddlewareHandler as MiddlewareHandler$1 } from 'hono/types';
 import { loadVendor as loadVendor$2, ToOpenAPISchemaContext } from '@standard-community/standard-openapi';
@@ -83,9 +84,34 @@ declare const uniqueSymbol: unique symbol;
 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 const setSpecComponents: (spec: object, components: OpenAPIV3_1.ComponentsObject[]) => WeakMap<object, OpenAPIV3_1.ComponentsObject[]>;
+declare const getSpecComponents: (spec: unknown) => OpenAPIV3_1.ComponentsObject[];
 declare function clearSpecsContext(): void;
-declare function registerSchemaPath({ route, specs, paths, }: RegisterSchemaPathOptions): void;
+declare function registerSchemaPath({ route, specs, paths }: RegisterSchemaPathOptions, pathContext?: Map<string, Omit<OpenAPIV3_1.OperationObject<{}>, "responses" | "operationId" | "requestBody"> & {
+    operationId?: string | ((route: RouterRoute) => string);
+    requestBody?: OpenAPIV3_1.ReferenceObject | (Omit<OpenAPIV3_1.RequestBodyObject, "content"> & {
+        content: ContentWithResolver;
+    });
+    hide?: boolean | ((props: {
+        c?: hono.Context;
+        method: string;
+        path: string;
+    }) => boolean);
+    responses?: ResponsesWithResolver;
+} & {
+    operationId?: string | ((route: RouterRoute) => string);
+}>): void;
 declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: SpecContext): OpenAPIV3_1.PathsObject<{}, {}>;
+/**
+ * Keeps the generated components that the documented operations brought in,
+ * and the ones `documentation` refers to, directly or through other
+ * components.
+ *
+ * Components are collected from every route while the paths are generated,
+ * including routes that are hidden or excluded afterwards. Without this, those
+ * routes would still publish the schemas only they use.
+ */
+declare function documentedComponents(components: OpenAPIV3_1.ComponentsObject, paths: OpenAPIV3_1.PathsObject, documentation: unknown): OpenAPIV3_1.ComponentsObject;
 
 type PromiseOr<T> = T | Promise<T>;
 type ResolverReturnType = ReturnType<typeof resolver> & {
@@ -265,4 +291,4 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
     jsonSchemaDialect?: string;
 }>;
 
-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 };
+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, documentedComponents, generateSpecs, getSpecComponents, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, setSpecComponents, uniqueSymbol, validator };

package/dist/index.js

@@ -53,10 +53,13 @@ function mergeParameters(...params) {
   }, /* @__PURE__ */ new Map());
   return Array.from(merged.values());
 }
+const specComponents = /* @__PURE__ */ new WeakMap();
+const setSpecComponents = (spec, components) => specComponents.set(spec, components);
+const getSpecComponents = (spec) => spec != null && typeof spec === "object" && specComponents.get(spec) || [];
 const specsByPathContext = /* @__PURE__ */ new Map();
-function getPathContext(path) {
+function getPathContext(path, pathContext) {
   const context = [];
-  for (const [key, data] of specsByPathContext) {
+  for (const [key, data] of pathContext) {
     if (!data) continue;
     const prefix = key.endsWith("/*") ? key.slice(0, -2) : key;
     if (path === prefix || path.startsWith(`${prefix}/`)) {
@@ -68,8 +71,21 @@ function getPathContext(path) {
 function clearSpecsContext() {
   specsByPathContext.clear();
 }
+function mergeRequestBodies(previous, current) {
+  if (!previous || !current || "$ref" in previous || "$ref" in current) {
+    return current;
+  }
+  return {
+    ...previous,
+    ...current,
+    content: {
+      ...previous.content,
+      ...current.content
+    }
+  };
+}
 function mergeSpecs(route, ...specs) {
-  return specs.reduce(
+  const merged = specs.reduce(
     (prev, spec) => {
       if (!spec || !prev) return prev;
       for (const [key, value] of Object.entries(spec)) {
@@ -89,6 +105,11 @@ function mergeSpecs(route, ...specs) {
           } else {
             if (key === "parameters") {
               prev[key] = mergeParameters(prev[key], value);
+            } else if (key === "requestBody") {
+              prev.requestBody = mergeRequestBodies(
+                prev.requestBody,
+                value
+              );
             } else {
               prev[key] = {
                 ...prev[key],
@@ -106,31 +127,29 @@ function mergeSpecs(route, ...specs) {
       operationId: generateOperationId(route)
     }
   );
+  setSpecComponents(merged, specs.flatMap(getSpecComponents));
+  return merged;
 }
-function registerSchemaPath({
-  route,
-  specs,
-  paths
-}) {
+function registerSchemaPath({ route, specs, paths }, pathContext = specsByPathContext) {
   const path = toOpenAPIPath(route.path);
   const method = route.method.toLowerCase();
   if (method === "all") {
     if (!specs) return;
-    if (specsByPathContext.has(path)) {
-      const prev = specsByPathContext.get(path) ?? {};
-      specsByPathContext.set(path, mergeSpecs(route, prev, specs));
+    if (pathContext.has(path)) {
+      const prev = pathContext.get(path) ?? {};
+      pathContext.set(path, mergeSpecs(route, prev, specs));
     } else {
-      specsByPathContext.set(path, specs);
+      pathContext.set(path, specs);
     }
   } else {
-    const pathContext = getPathContext(path);
+    const context = getPathContext(path, pathContext);
     if (!(path in paths)) {
       paths[path] = {};
     }
     if (paths[path]) {
       paths[path][method] = mergeSpecs(
         route,
-        ...pathContext,
+        ...context,
         paths[path]?.[method],
         specs
       );
@@ -224,6 +243,52 @@ function removeExcludedPaths(paths, ctx) {
   }
   return newPaths;
 }
+const COMPONENTS_PREFIX = "#/components/";
+const componentKey = (type, name) => `${type}/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+const componentRefs = (value) => {
+  if (Array.isArray(value)) {
+    return value.flatMap(componentRefs);
+  }
+  if (value == null || typeof value !== "object") {
+    return [];
+  }
+  return Object.entries(value).flatMap(([key, item]) => {
+    if (key !== "$ref" || typeof item !== "string") {
+      return componentRefs(item);
+    }
+    return item.startsWith(COMPONENTS_PREFIX) ? [item.slice(COMPONENTS_PREFIX.length)] : [];
+  });
+};
+const reachableRefs = (refs, components, reached) => refs.reduce((seen, ref) => {
+  if (seen.has(ref)) {
+    return seen;
+  }
+  const [type, ...name] = ref.split("/");
+  const component = components[type]?.[name.join("/").replaceAll("~1", "/").replaceAll("~0", "~")];
+  return reachableRefs(componentRefs(component), components, seen.add(ref));
+}, reached);
+function documentedComponents(components, paths, documentation) {
+  const contributed = new Set(
+    Object.values(paths).flatMap((item) => item == null ? [] : Object.values(item)).flatMap(getSpecComponents).flatMap(
+      (operationComponents) => Object.entries(operationComponents).flatMap(
+        ([type, entries]) => Object.keys(entries ?? {}).map((name) => componentKey(type, name))
+      )
+    )
+  );
+  const kept = reachableRefs(
+    componentRefs(documentation),
+    components,
+    contributed
+  );
+  return Object.fromEntries(
+    Object.entries(components).flatMap(([type, entries]) => {
+      const remaining = Object.entries(entries ?? {}).filter(
+        ([name]) => kept.has(componentKey(type, name))
+      );
+      return remaining.length > 0 ? [[type, Object.fromEntries(remaining)]] : [];
+    })
+  );
+}
 
 const DEFAULT_OPTIONS = {
   documentation: {},
@@ -275,7 +340,6 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     ..._documentation,
     components: _documentation.components && { ..._documentation.components }
   };
-  clearSpecsContext();
   const paths = await generatePaths(hono, ctx);
   for (const path in paths) {
     for (const method in paths[path]) {
@@ -294,10 +358,14 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
   if (resolvedDocumentation && documentation.components) {
     documentation.components.responses = resolvedDocumentation.responses;
   }
+  const documentedPaths = removeExcludedPaths(paths, ctx);
   const components = mergeComponentsObjects(
     documentation.components,
     resolvedDocumentation?.components,
-    ctx.components
+    documentedComponents(ctx.components, documentedPaths, [
+      documentation,
+      resolvedDocumentation?.components
+    ])
   );
   return {
     openapi: "3.1.0",
@@ -312,7 +380,7 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       ...documentation.info
     },
     paths: {
-      ...removeExcludedPaths(paths, ctx),
+      ...documentedPaths,
       ...documentation.paths
     },
     components
@@ -320,14 +388,18 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
 }
 async function generatePaths(hono, ctx) {
   const paths = {};
+  const pathContext = /* @__PURE__ */ new Map();
   for (const route of hono.routes) {
     const middlewareHandler = findTargetHandler(route.handler)[uniqueSymbol];
     if (!middlewareHandler) {
       if (ctx.options.includeEmptyPaths) {
-        registerSchemaPath({
-          route,
-          paths
-        });
+        registerSchemaPath(
+          {
+            route,
+            paths
+          },
+          pathContext
+        );
       }
       continue;
     }
@@ -343,14 +415,19 @@ async function generatePaths(hono, ctx) {
     const defaultOptionsForThisMethod = ctx.options.defaultOptions?.[routeMethod] && { ...ctx.options.defaultOptions[routeMethod] };
     const { schema: routeSpecs, components = {} } = await getSpec(
       middlewareHandler,
-      defaultOptionsForThisMethod
+      defaultOptionsForThisMethod,
+      ctx.components.parameters
     );
     ctx.components = mergeComponentsObjects(ctx.components, components);
-    registerSchemaPath({
-      route,
-      specs: routeSpecs,
-      paths
-    });
+    setSpecComponents(routeSpecs, [components]);
+    registerSchemaPath(
+      {
+        route,
+        specs: routeSpecs,
+        paths
+      },
+      pathContext
+    );
   }
   return paths;
 }
@@ -366,7 +443,7 @@ function getHiddenValue(options) {
   }
   return false;
 }
-async function getSpec(middlewareHandler, defaultOptions) {
+async function getSpec(middlewareHandler, defaultOptions, parameterComponents) {
   if ("spec" in middlewareHandler) {
     const tmp = {
       ...defaultOptions,
@@ -401,7 +478,7 @@ async function getSpec(middlewareHandler, defaultOptions) {
     [VALIDATION_MARKER]: true
   };
   if (middlewareHandler.target === "form" || middlewareHandler.target === "json") {
-    const media = middlewareHandler.options?.media ?? middlewareHandler.target === "json" ? "application/json" : "multipart/form-data";
+    const media = middlewareHandler.options?.media ?? (middlewareHandler.target === "json" ? "application/json" : "multipart/form-data");
     if (!docs.requestBody || !("content" in docs.requestBody) || !docs.requestBody.content) {
       docs.requestBody = {
         required: true,
@@ -423,18 +500,21 @@ async function getSpec(middlewareHandler, defaultOptions) {
       const pos = ref.split("/").pop();
       if (pos && result.components?.schemas?.[pos]) {
         const schema = result.components.schemas[pos];
-        const newParameters = generateParameters(
+        const generatedParameters = generateParameters(
           middlewareHandler.target,
-          schema
-        )[0];
-        if (!result.components.parameters) {
-          result.components.parameters = {};
+          schema,
+          result.components.schemas
+        );
+        const singleParameter = generatedParameters.length === 1 ? generatedParameters[0] : void 0;
+        const existingParameter = parameterComponents?.[pos];
+        if (singleParameter && (!existingParameter || "in" in existingParameter && existingParameter.in === singleParameter.in && existingParameter.name === singleParameter.name)) {
+          result.components.parameters ??= {};
+          result.components.parameters[pos] = singleParameter;
+          parameters.push({ $ref: `#/components/parameters/${pos}` });
+          delete result.components.schemas[pos];
+        } else {
+          parameters = generatedParameters;
         }
-        result.components.parameters[pos] = newParameters;
-        delete result.components.schemas[pos];
-        parameters.push({
-          $ref: `#/components/parameters/${pos}`
-        });
       }
     } else {
       parameters = generateParameters(
@@ -688,4 +768,4 @@ function describeResponse(handler, responses, options) {
   });
 }
 
-export { ALLOWED_METHODS, VALIDATION_MARKER, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };
+export { ALLOWED_METHODS, VALIDATION_MARKER, clearSpecsContext, describeResponse, describeRoute, documentedComponents, generateSpecs, getSpecComponents, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, setSpecComponents, uniqueSymbol, validator };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hono-openapi",
   "description": "OpenAPI schema generator for Hono",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",