hono-openapi 0.5.0-rc.3 → 1.0.0

package/dist/index.cjs

@@ -31,12 +31,7 @@ const toOpenAPIPath = (path) => path.split("/").map((x) => {
   return tmp;
 }).join("/");
 const capitalize = (word) => word.charAt(0).toUpperCase() + word.slice(1);
-const generateOperationIdCache = /* @__PURE__ */ new Map();
 const generateOperationId = (route) => {
-  const operationIdKey = `${route.method}:${route.path}`;
-  if (generateOperationIdCache.has(operationIdKey)) {
-    return generateOperationIdCache.get(operationIdKey);
-  }
   let operationId = route.method;
   if (route.path === "/") return `${operationId}Index`;
   for (const segment of route.path.split("/")) {
@@ -46,61 +41,61 @@ const generateOperationId = (route) => {
       operationId += capitalize(segment);
     }
   }
-  generateOperationIdCache.set(operationIdKey, operationId);
   return operationId;
 };
 const paramKey = (param) => "$ref" in param ? param.$ref : `${param.in} ${param.name}`;
 function mergeParameters(...params) {
-  const _params = params.flatMap((x) => x ?? []);
-  const merged = _params.reduce((acc, param) => {
+  const merged = params.flatMap((x) => x ?? []).reduce((acc, param) => {
     acc.set(paramKey(param), param);
     return acc;
   }, /* @__PURE__ */ new Map());
   return Array.from(merged.values());
 }
-function getProperty(obj, key, defaultValue) {
-  if (obj != null && key in obj) {
-    return obj[key];
-  }
-  return defaultValue;
-}
 const specsByPathContext = /* @__PURE__ */ new Map();
 function getPathContext(path) {
-  const keys = Array.from(specsByPathContext.keys());
   const context = [];
-  for (const key of keys) {
-    if (path.match(key)) {
-      const data = specsByPathContext.get(key);
-      if (!data) continue;
+  for (const [key, data] of specsByPathContext) {
+    if (data && path.match(key)) {
       context.push(data);
     }
   }
   return context;
 }
-function mergeSpecs(...specs) {
+function mergeSpecs(route, ...specs) {
   return specs.reduce(
     (prev, spec) => {
-      if (!spec) return prev;
-      return {
-        ...prev,
-        ...spec,
-        tags: Array.from(
-          /* @__PURE__ */ new Set([
-            ...getProperty(prev, "tags") ?? [],
-            ...getProperty(spec, "tags") ?? []
-          ])
-        ),
-        parameters: mergeParameters(
-          getProperty(prev, "parameters"),
-          getProperty(spec, "parameters")
-        ),
-        responses: {
-          ...getProperty(prev, "responses", {}),
-          ...getProperty(spec, "responses", {})
+      if (!spec || !prev) return prev;
+      for (const [key, value] of Object.entries(spec)) {
+        if (value == null) continue;
+        if (key in prev && (typeof value === "object" || typeof value === "function" && key === "operationId")) {
+          if (Array.isArray(value)) {
+            const values = [...prev[key] ?? [], ...value];
+            if (key === "tags") {
+              prev[key] = Array.from(new Set(values));
+            } else {
+              prev[key] = values;
+            }
+          } else if (typeof value === "function") {
+            prev[key] = value(route);
+          } else {
+            if (key === "parameters") {
+              prev[key] = mergeParameters(prev[key], value);
+            } else {
+              prev[key] = {
+                ...prev[key],
+                ...value
+              };
+            }
+          }
+        } else {
+          prev[key] = value;
         }
-      };
+      }
+      return prev;
     },
-    {}
+    {
+      operationId: generateOperationId(route)
+    }
   );
 }
 function registerSchemaPath({
@@ -114,19 +109,23 @@ function registerSchemaPath({
     if (!specs) return;
     if (specsByPathContext.has(path)) {
       const prev = specsByPathContext.get(path) ?? {};
-      specsByPathContext.set(path, mergeSpecs(prev, specs));
+      specsByPathContext.set(path, mergeSpecs(route, prev, specs));
     } else {
       specsByPathContext.set(path, specs);
     }
   } else {
     const pathContext = getPathContext(path);
-    paths[path] = {
-      ...paths[path] ? paths[path] : {},
-      [method]: {
-        operationId: generateOperationId(route),
-        ...mergeSpecs(...pathContext, paths[path]?.[method], specs)
-      }
-    };
+    if (!(path in paths)) {
+      paths[path] = {};
+    }
+    if (paths[path]) {
+      paths[path][method] = mergeSpecs(
+        route,
+        ...pathContext,
+        paths[path]?.[method],
+        specs
+      );
+    }
   }
 }
 function removeExcludedPaths(paths, ctx) {
@@ -152,10 +151,21 @@ function removeExcludedPaths(paths, ctx) {
           for (const param of pathParameters) {
             const paramName = param.slice(1, param.length - 1);
             const index = schema.parameters.findIndex(
-              (x) => x.in === "param" && x.name === paramName
+              (x) => {
+                if ("$ref" in x) {
+                  const pos = x.$ref.split("/").pop();
+                  if (pos) {
+                    const param2 = ctx.components.parameters?.[pos];
+                    if (param2 && !("$ref" in param2)) {
+                      return param2.in === "path" && param2.name === paramName;
+                    }
+                  }
+                  return false;
+                }
+                return x.in === "path" && x.name === paramName;
+              }
             );
-            if (index !== -1) schema.parameters[index].in = "path";
-            else {
+            if (index === -1) {
               schema.parameters.push({
                 schema: { type: "string" },
                 in: "path",
@@ -202,20 +212,24 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     }
   };
   const _documentation = ctx.options.documentation ?? {};
-  const schema = await generatePaths(hono, ctx);
-  for (const path in schema) {
-    for (const method in schema[path]) {
+  const paths = await generatePaths(hono, ctx);
+  for (const path in paths) {
+    for (const method in paths[path]) {
       const isHidden = getHiddenValue({
-        valueOrFunc: schema[path][method]?.hide,
+        valueOrFunc: paths[path][method]?.hide,
         method,
         path,
         c
       });
       if (isHidden) {
-        delete schema[path][method];
+        paths[path][method] = void 0;
       }
     }
   }
+  const components = mergeComponentsObjects(
+    _documentation.components,
+    ctx.components
+  );
   return {
     openapi: "3.1.0",
     ..._documentation,
@@ -229,22 +243,17 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       ..._documentation.info
     },
     paths: {
-      ...removeExcludedPaths(schema, ctx),
+      ...removeExcludedPaths(paths, ctx),
       ..._documentation.paths
     },
-    components: {
-      ..._documentation.components,
-      schemas: {
-        ...ctx.components.schemas,
-        ..._documentation.components?.schemas
-      }
-    }
+    components
   };
 }
 async function generatePaths(hono, ctx) {
   const paths = {};
   for (const route of hono.routes) {
-    if (!(uniqueSymbol in route.handler)) {
+    const middlewareHandler = route.handler[uniqueSymbol];
+    if (!middlewareHandler) {
       if (ctx.options.includeEmptyPaths) {
         registerSchemaPath({
           route,
@@ -262,20 +271,12 @@ async function generatePaths(hono, ctx) {
         continue;
       }
     }
-    const middlewareHandler = route.handler[uniqueSymbol];
     const defaultOptionsForThisMethod = ctx.options.defaultOptions?.[routeMethod];
     const { schema: routeSpecs, components = {} } = await getSpec(
       middlewareHandler,
       defaultOptionsForThisMethod
     );
-    ctx.components = {
-      ...ctx.components,
-      ...components,
-      schemas: {
-        ...ctx.components.schemas,
-        ...components.schemas
-      }
-    };
+    ctx.components = mergeComponentsObjects(ctx.components, components);
     registerSchemaPath({
       route,
       specs: routeSpecs,
@@ -289,14 +290,9 @@ function getHiddenValue(options) {
   if (valueOrFunc != null) {
     if (typeof valueOrFunc === "boolean") {
       return valueOrFunc;
-    } else if (typeof valueOrFunc === "function") {
-      if (c) {
-        return valueOrFunc(c);
-      } else {
-        console.warn(
-          `'c' is not defined, cannot evaluate hide function for ${method} ${path}`
-        );
-      }
+    }
+    if (typeof valueOrFunc === "function") {
+      return valueOrFunc({ c, method, path });
     }
   }
   return false;
@@ -320,7 +316,7 @@ async function getSpec(middlewareHandler, defaultOptions) {
           const raw = response.content?.[contentKey];
           if (!raw) continue;
           if (raw.schema && "toOpenAPISchema" in raw.schema) {
-            const result2 = await raw.schema.toOpenAPISchema(defaultOptions);
+            const result2 = await raw.schema.toOpenAPISchema();
             raw.schema = result2.schema;
             if (result2.components) {
               components = {
@@ -337,7 +333,7 @@ async function getSpec(middlewareHandler, defaultOptions) {
   const result = await middlewareHandler.toOpenAPISchema();
   const docs = {};
   if (middlewareHandler.target === "form" || middlewareHandler.target === "json") {
-    const 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 = {
         content: {
@@ -352,39 +348,78 @@ async function getSpec(middlewareHandler, defaultOptions) {
       };
     }
   } else {
-    const parameters = [];
+    let parameters = [];
     if ("$ref" in result.schema) {
-      parameters.push({
-        in: middlewareHandler.target,
-        // @ts-expect-error
-        name: result.schema.$ref,
-        // @ts-expect-error
-        schema: result.schema
-      });
-    } else {
-      for (const [key, value] of Object.entries(
-        result.schema.properties ?? {}
-      )) {
+      const ref = result.schema.$ref;
+      const pos = ref.split("/").pop();
+      if (pos && result.components?.schemas?.[pos]) {
+        const schema = result.components.schemas[pos];
+        const newParameters = generateParameters(
+          middlewareHandler.target,
+          schema
+        )[0];
+        if (!result.components.parameters) {
+          result.components.parameters = {};
+        }
+        result.components.parameters[pos] = newParameters;
+        delete result.components.schemas[pos];
         parameters.push({
-          in: middlewareHandler.target,
-          name: key,
-          // @ts-expect-error
-          schema: value,
-          required: result.schema.required?.includes(key)
+          $ref: `#/components/parameters/${pos}`
         });
       }
+    } else {
+      parameters = generateParameters(middlewareHandler.target, result.schema);
     }
     docs.parameters = parameters;
   }
   return { schema: docs, components: result.components };
 }
+function generateParameters(target, schema) {
+  const parameters = [];
+  for (const [key, value] of Object.entries(schema.properties ?? {})) {
+    const def = {
+      in: target === "param" ? "path" : target,
+      name: key,
+      // @ts-expect-error
+      schema: value,
+      required: schema.required?.includes(key)
+    };
+    if (def.schema && "description" in def.schema && def.schema.description) {
+      def.description = def.schema.description;
+      def.schema.description = void 0;
+    }
+    parameters.push(def);
+  }
+  return parameters;
+}
+function mergeComponentsObjects(...components) {
+  return components.reduce(
+    (prev, component, index) => {
+      if (!component || index === 0) return prev;
+      if (prev.schemas && Object.keys(prev.schemas).length > 0 || component.schemas && Object.keys(component.schemas).length > 0) {
+        prev.schemas = {
+          ...prev.schemas,
+          ...component.schemas
+        };
+      }
+      if (prev.parameters && Object.keys(prev.parameters).length > 0 || component.parameters && Object.keys(component.parameters).length > 0) {
+        prev.parameters = {
+          ...prev.parameters,
+          ...component.parameters
+        };
+      }
+      return prev;
+    },
+    components[0] ?? {}
+  );
+}
 
-function resolver(schema) {
+function resolver(schema, options) {
   return {
     vendor: schema["~standard"].vendor,
     validate: schema["~standard"].validate,
-    toJSONSchema: (options) => standardJson.toJsonSchema(schema, options),
-    toOpenAPISchema: (options) => standardOpenapi.toOpenAPISchema(schema, options)
+    toJSONSchema: () => standardJson.toJsonSchema(schema, options),
+    toOpenAPISchema: () => standardOpenapi.toOpenAPISchema(schema, options)
   };
 }
 function validator(target, schema, hook, options) {
@@ -392,7 +427,7 @@ function validator(target, schema, hook, options) {
   return Object.assign(middleware, {
     [uniqueSymbol]: {
       target,
-      ...resolver(schema),
+      ...resolver(schema, options),
       options
     }
   });
@@ -407,16 +442,17 @@ function describeRoute(spec) {
     }
   });
 }
-function describeResponse(handler, responses) {
+function describeResponse(handler, responses, options) {
   const _responses = Object.entries(responses).reduce(
     (acc, [statusCode, response]) => {
       if (response.content) {
         const content = Object.entries(response.content).reduce(
           (contentAcc, [mediaType, media]) => {
             if (media.vSchema) {
+              const { vSchema, ...rest } = media;
               contentAcc[mediaType] = {
-                ...media,
-                schema: resolver(media.vSchema)
+                ...rest,
+                schema: resolver(vSchema, options)
               };
             } else {
               contentAcc[mediaType] = media;

package/dist/index.d.cts

@@ -68,11 +68,11 @@ declare namespace StandardSchemaV1 {
  * @param schema Validation schema
  * @returns Resolver result
  */
-declare function resolver<Schema extends StandardSchemaV1>(schema: Schema): {
+declare function resolver<Schema extends StandardSchemaV1>(schema: Schema, options?: Record<string, unknown>): {
     vendor: string;
     validate: (value: unknown) => StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;
-    toJSONSchema: (options?: Record<string, unknown>) => Promise<json_schema.JSONSchema7>;
-    toOpenAPISchema: (options?: Record<string, unknown>) => Promise<{
+    toJSONSchema: () => Promise<json_schema.JSONSchema7>;
+    toOpenAPISchema: () => Promise<{
         schema: OpenAPIV3_1.SchemaObject;
         components: OpenAPIV3_1.ComponentsObject | undefined;
     }>;
@@ -98,7 +98,7 @@ declare function validator<Schema extends StandardSchemaV1, Target extends keyof
     out: {
         [K in Target]: Out;
     };
-}, V extends I = I>(target: Target, schema: Schema, hook?: Hook<StandardSchemaV1.InferOutput<Schema>, E, P, Target>, options?: Record<string, unknown>): MiddlewareHandler<E, P, V>;
+}, V extends I = I>(target: Target, schema: Schema, hook?: Hook<StandardSchemaV1.InferOutput<Schema>, E, P, Target>, options?: ResolverReturnType["options"]): MiddlewareHandler<E, P, V>;
 /**
  * Describe a route with OpenAPI specs.
  * @param spec Options for describing a route
@@ -119,7 +119,7 @@ type HandlerResponse<T extends Partial<Record<StatusCode, StandardSchemaV1>> = P
     [K in keyof T]: T[K] extends StandardSchemaV1 ? PromiseOr<TypedResponse<StandardSchemaV1.InferOutput<T[K]>, Num<K> extends StatusCode ? Num<K> : never>> : never;
 }[keyof T];
 type Handler<E extends Env = any, P extends string = any, I extends Input = BlankInput, T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>> = (c: Context<E, P, I>, next: Next) => HandlerResponse<T>;
-declare function describeResponse<E extends Env = any, P extends string = any, I extends Input = BlankInput, T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>>(handler: Handler<E, P, I, T>, responses: ResponseObject<T>): Handler<E, P, I, T>;
+declare function describeResponse<E extends Env = any, P extends string = any, I extends Input = BlankInput, T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>>(handler: Handler<E, P, I, T>, responses: ResponseObject<T>, options?: Record<string, unknown>): Handler<E, P, I, T>;
 
 /**
  * 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.
@@ -128,15 +128,21 @@ declare const uniqueSymbol: unique symbol;
 declare const ALLOWED_METHODS: readonly ["GET", "PUT", "POST", "DELETE", "OPTIONS", "HEAD", "PATCH", "TRACE"];
 type AllowedMethods = (typeof ALLOWED_METHODS)[number];
 declare function registerSchemaPath({ route, specs, paths, }: RegisterSchemaPathOptions): void;
-declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: {
-    options: SanitizedGenerateSpecOptions;
-}): OpenAPIV3_1.PathsObject<{}, {}>;
+declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: SpecContext): OpenAPIV3_1.PathsObject<{}, {}>;
 
 type PromiseOr<T> = T | Promise<T>;
-type ResolverReturnType = ReturnType<typeof resolver>;
+type ResolverReturnType = ReturnType<typeof resolver> & {
+    options?: {
+        /**
+         * Override the media type of the request body, if not specified, it will be `application/json` for `json` target and `multipart/form-data` for `form` target.
+         */
+        media?: string;
+    } & {
+        [key: string]: unknown;
+    };
+};
 type HandlerUniqueProperty = (ResolverReturnType & {
     target: keyof ValidationTargets$1;
-    options?: Record<string, unknown>;
 }) | {
     spec: DescribeRouteOptions;
 };
@@ -178,13 +184,15 @@ type GenerateSpecOptions = {
      */
     defaultOptions: Partial<Record<AllowedMethods | "ALL", DescribeRouteOptions>>;
 };
-type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags";
-type SanitizedGenerateSpecOptions = Pick<GenerateSpecOptions, HaveDefaultValues> & Omit<Partial<GenerateSpecOptions>, HaveDefaultValues>;
 type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "responses" | "parameters"> & {
     /**
      * Pass `true` to hide route from OpenAPI/swagger document
      */
-    hide?: boolean | ((c: Context) => boolean);
+    hide?: boolean | ((props: {
+        c?: Context;
+        method: string;
+        path: string;
+    }) => boolean);
     /**
      * Responses of the request
      */
@@ -200,9 +208,17 @@ type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "responses" | "par
 };
 type RegisterSchemaPathOptions = {
     route: RouterRoute;
-    specs?: DescribeRouteOptions | Pick<OpenAPIV3_1.OperationObject, "parameters" | "requestBody">;
+    specs?: DescribeRouteOptions & {
+        operationId?: string | ((route: RouterRoute) => string);
+    };
     paths: Partial<OpenAPIV3_1.PathsObject>;
 };
+type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags";
+type SanitizedGenerateSpecOptions = Pick<GenerateSpecOptions, HaveDefaultValues> & Omit<Partial<GenerateSpecOptions>, HaveDefaultValues>;
+type SpecContext = {
+    components: OpenAPIV3_1.ComponentsObject;
+    options: SanitizedGenerateSpecOptions;
+};
 
 /**
  * Route handler for OpenAPI specs
@@ -245,20 +261,7 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
             trace?: OpenAPIV3_1.OperationObject<{}>;
         };
     };
-    components: {
-        schemas: {
-            [x: string]: OpenAPIV3_1.SchemaObject;
-        };
-        responses?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ResponseObject>;
-        parameters?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject>;
-        examples?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ExampleObject>;
-        requestBodies?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.RequestBodyObject>;
-        headers?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.HeaderObject>;
-        securitySchemes?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SecuritySchemeObject>;
-        links?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.LinkObject>;
-        callbacks?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.CallbackObject>;
-        pathItems?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.PathItemObject>;
-    };
+    components: OpenAPIV3_1.ComponentsObject;
     openapi: string;
     externalDocs?: openapi_types.OpenAPIV3.ExternalDocumentationObject;
     security?: openapi_types.OpenAPIV3.SecurityRequirementObject[];
@@ -267,4 +270,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 SanitizedGenerateSpecOptions, describeResponse, describeRoute, generateSpecs, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };
+export { ALLOWED_METHODS, type AllowedMethods, type DescribeRouteOptions, type GenerateSpecOptions, type HandlerUniqueProperty, type PromiseOr, type RegisterSchemaPathOptions, type ResolverReturnType, type SpecContext, describeResponse, describeRoute, generateSpecs, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/dist/index.d.ts

@@ -68,11 +68,11 @@ declare namespace StandardSchemaV1 {
  * @param schema Validation schema
  * @returns Resolver result
  */
-declare function resolver<Schema extends StandardSchemaV1>(schema: Schema): {
+declare function resolver<Schema extends StandardSchemaV1>(schema: Schema, options?: Record<string, unknown>): {
     vendor: string;
     validate: (value: unknown) => StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;
-    toJSONSchema: (options?: Record<string, unknown>) => Promise<json_schema.JSONSchema7>;
-    toOpenAPISchema: (options?: Record<string, unknown>) => Promise<{
+    toJSONSchema: () => Promise<json_schema.JSONSchema7>;
+    toOpenAPISchema: () => Promise<{
         schema: OpenAPIV3_1.SchemaObject;
         components: OpenAPIV3_1.ComponentsObject | undefined;
     }>;
@@ -98,7 +98,7 @@ declare function validator<Schema extends StandardSchemaV1, Target extends keyof
     out: {
         [K in Target]: Out;
     };
-}, V extends I = I>(target: Target, schema: Schema, hook?: Hook<StandardSchemaV1.InferOutput<Schema>, E, P, Target>, options?: Record<string, unknown>): MiddlewareHandler<E, P, V>;
+}, V extends I = I>(target: Target, schema: Schema, hook?: Hook<StandardSchemaV1.InferOutput<Schema>, E, P, Target>, options?: ResolverReturnType["options"]): MiddlewareHandler<E, P, V>;
 /**
  * Describe a route with OpenAPI specs.
  * @param spec Options for describing a route
@@ -119,7 +119,7 @@ type HandlerResponse<T extends Partial<Record<StatusCode, StandardSchemaV1>> = P
     [K in keyof T]: T[K] extends StandardSchemaV1 ? PromiseOr<TypedResponse<StandardSchemaV1.InferOutput<T[K]>, Num<K> extends StatusCode ? Num<K> : never>> : never;
 }[keyof T];
 type Handler<E extends Env = any, P extends string = any, I extends Input = BlankInput, T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>> = (c: Context<E, P, I>, next: Next) => HandlerResponse<T>;
-declare function describeResponse<E extends Env = any, P extends string = any, I extends Input = BlankInput, T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>>(handler: Handler<E, P, I, T>, responses: ResponseObject<T>): Handler<E, P, I, T>;
+declare function describeResponse<E extends Env = any, P extends string = any, I extends Input = BlankInput, T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>>(handler: Handler<E, P, I, T>, responses: ResponseObject<T>, options?: Record<string, unknown>): Handler<E, P, I, T>;
 
 /**
  * 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.
@@ -128,15 +128,21 @@ declare const uniqueSymbol: unique symbol;
 declare const ALLOWED_METHODS: readonly ["GET", "PUT", "POST", "DELETE", "OPTIONS", "HEAD", "PATCH", "TRACE"];
 type AllowedMethods = (typeof ALLOWED_METHODS)[number];
 declare function registerSchemaPath({ route, specs, paths, }: RegisterSchemaPathOptions): void;
-declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: {
-    options: SanitizedGenerateSpecOptions;
-}): OpenAPIV3_1.PathsObject<{}, {}>;
+declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: SpecContext): OpenAPIV3_1.PathsObject<{}, {}>;
 
 type PromiseOr<T> = T | Promise<T>;
-type ResolverReturnType = ReturnType<typeof resolver>;
+type ResolverReturnType = ReturnType<typeof resolver> & {
+    options?: {
+        /**
+         * Override the media type of the request body, if not specified, it will be `application/json` for `json` target and `multipart/form-data` for `form` target.
+         */
+        media?: string;
+    } & {
+        [key: string]: unknown;
+    };
+};
 type HandlerUniqueProperty = (ResolverReturnType & {
     target: keyof ValidationTargets$1;
-    options?: Record<string, unknown>;
 }) | {
     spec: DescribeRouteOptions;
 };
@@ -178,13 +184,15 @@ type GenerateSpecOptions = {
      */
     defaultOptions: Partial<Record<AllowedMethods | "ALL", DescribeRouteOptions>>;
 };
-type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags";
-type SanitizedGenerateSpecOptions = Pick<GenerateSpecOptions, HaveDefaultValues> & Omit<Partial<GenerateSpecOptions>, HaveDefaultValues>;
 type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "responses" | "parameters"> & {
     /**
      * Pass `true` to hide route from OpenAPI/swagger document
      */
-    hide?: boolean | ((c: Context) => boolean);
+    hide?: boolean | ((props: {
+        c?: Context;
+        method: string;
+        path: string;
+    }) => boolean);
     /**
      * Responses of the request
      */
@@ -200,9 +208,17 @@ type DescribeRouteOptions = Omit<OpenAPIV3_1.OperationObject, "responses" | "par
 };
 type RegisterSchemaPathOptions = {
     route: RouterRoute;
-    specs?: DescribeRouteOptions | Pick<OpenAPIV3_1.OperationObject, "parameters" | "requestBody">;
+    specs?: DescribeRouteOptions & {
+        operationId?: string | ((route: RouterRoute) => string);
+    };
     paths: Partial<OpenAPIV3_1.PathsObject>;
 };
+type HaveDefaultValues = "documentation" | "excludeStaticFile" | "exclude" | "excludeMethods" | "excludeTags";
+type SanitizedGenerateSpecOptions = Pick<GenerateSpecOptions, HaveDefaultValues> & Omit<Partial<GenerateSpecOptions>, HaveDefaultValues>;
+type SpecContext = {
+    components: OpenAPIV3_1.ComponentsObject;
+    options: SanitizedGenerateSpecOptions;
+};
 
 /**
  * Route handler for OpenAPI specs
@@ -245,20 +261,7 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
             trace?: OpenAPIV3_1.OperationObject<{}>;
         };
     };
-    components: {
-        schemas: {
-            [x: string]: OpenAPIV3_1.SchemaObject;
-        };
-        responses?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ResponseObject>;
-        parameters?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ParameterObject>;
-        examples?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.ExampleObject>;
-        requestBodies?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.RequestBodyObject>;
-        headers?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.HeaderObject>;
-        securitySchemes?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.SecuritySchemeObject>;
-        links?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.LinkObject>;
-        callbacks?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.CallbackObject>;
-        pathItems?: Record<string, OpenAPIV3_1.ReferenceObject | OpenAPIV3_1.PathItemObject>;
-    };
+    components: OpenAPIV3_1.ComponentsObject;
     openapi: string;
     externalDocs?: openapi_types.OpenAPIV3.ExternalDocumentationObject;
     security?: openapi_types.OpenAPIV3.SecurityRequirementObject[];
@@ -267,4 +270,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 SanitizedGenerateSpecOptions, describeResponse, describeRoute, generateSpecs, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };
+export { ALLOWED_METHODS, type AllowedMethods, type DescribeRouteOptions, type GenerateSpecOptions, type HandlerUniqueProperty, type PromiseOr, type RegisterSchemaPathOptions, type ResolverReturnType, type SpecContext, describeResponse, describeRoute, generateSpecs, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/dist/index.js

@@ -29,12 +29,7 @@ const toOpenAPIPath = (path) => path.split("/").map((x) => {
   return tmp;
 }).join("/");
 const capitalize = (word) => word.charAt(0).toUpperCase() + word.slice(1);
-const generateOperationIdCache = /* @__PURE__ */ new Map();
 const generateOperationId = (route) => {
-  const operationIdKey = `${route.method}:${route.path}`;
-  if (generateOperationIdCache.has(operationIdKey)) {
-    return generateOperationIdCache.get(operationIdKey);
-  }
   let operationId = route.method;
   if (route.path === "/") return `${operationId}Index`;
   for (const segment of route.path.split("/")) {
@@ -44,61 +39,61 @@ const generateOperationId = (route) => {
       operationId += capitalize(segment);
     }
   }
-  generateOperationIdCache.set(operationIdKey, operationId);
   return operationId;
 };
 const paramKey = (param) => "$ref" in param ? param.$ref : `${param.in} ${param.name}`;
 function mergeParameters(...params) {
-  const _params = params.flatMap((x) => x ?? []);
-  const merged = _params.reduce((acc, param) => {
+  const merged = params.flatMap((x) => x ?? []).reduce((acc, param) => {
     acc.set(paramKey(param), param);
     return acc;
   }, /* @__PURE__ */ new Map());
   return Array.from(merged.values());
 }
-function getProperty(obj, key, defaultValue) {
-  if (obj != null && key in obj) {
-    return obj[key];
-  }
-  return defaultValue;
-}
 const specsByPathContext = /* @__PURE__ */ new Map();
 function getPathContext(path) {
-  const keys = Array.from(specsByPathContext.keys());
   const context = [];
-  for (const key of keys) {
-    if (path.match(key)) {
-      const data = specsByPathContext.get(key);
-      if (!data) continue;
+  for (const [key, data] of specsByPathContext) {
+    if (data && path.match(key)) {
       context.push(data);
     }
   }
   return context;
 }
-function mergeSpecs(...specs) {
+function mergeSpecs(route, ...specs) {
   return specs.reduce(
     (prev, spec) => {
-      if (!spec) return prev;
-      return {
-        ...prev,
-        ...spec,
-        tags: Array.from(
-          /* @__PURE__ */ new Set([
-            ...getProperty(prev, "tags") ?? [],
-            ...getProperty(spec, "tags") ?? []
-          ])
-        ),
-        parameters: mergeParameters(
-          getProperty(prev, "parameters"),
-          getProperty(spec, "parameters")
-        ),
-        responses: {
-          ...getProperty(prev, "responses", {}),
-          ...getProperty(spec, "responses", {})
+      if (!spec || !prev) return prev;
+      for (const [key, value] of Object.entries(spec)) {
+        if (value == null) continue;
+        if (key in prev && (typeof value === "object" || typeof value === "function" && key === "operationId")) {
+          if (Array.isArray(value)) {
+            const values = [...prev[key] ?? [], ...value];
+            if (key === "tags") {
+              prev[key] = Array.from(new Set(values));
+            } else {
+              prev[key] = values;
+            }
+          } else if (typeof value === "function") {
+            prev[key] = value(route);
+          } else {
+            if (key === "parameters") {
+              prev[key] = mergeParameters(prev[key], value);
+            } else {
+              prev[key] = {
+                ...prev[key],
+                ...value
+              };
+            }
+          }
+        } else {
+          prev[key] = value;
         }
-      };
+      }
+      return prev;
     },
-    {}
+    {
+      operationId: generateOperationId(route)
+    }
   );
 }
 function registerSchemaPath({
@@ -112,19 +107,23 @@ function registerSchemaPath({
     if (!specs) return;
     if (specsByPathContext.has(path)) {
       const prev = specsByPathContext.get(path) ?? {};
-      specsByPathContext.set(path, mergeSpecs(prev, specs));
+      specsByPathContext.set(path, mergeSpecs(route, prev, specs));
     } else {
       specsByPathContext.set(path, specs);
     }
   } else {
     const pathContext = getPathContext(path);
-    paths[path] = {
-      ...paths[path] ? paths[path] : {},
-      [method]: {
-        operationId: generateOperationId(route),
-        ...mergeSpecs(...pathContext, paths[path]?.[method], specs)
-      }
-    };
+    if (!(path in paths)) {
+      paths[path] = {};
+    }
+    if (paths[path]) {
+      paths[path][method] = mergeSpecs(
+        route,
+        ...pathContext,
+        paths[path]?.[method],
+        specs
+      );
+    }
   }
 }
 function removeExcludedPaths(paths, ctx) {
@@ -150,10 +149,21 @@ function removeExcludedPaths(paths, ctx) {
           for (const param of pathParameters) {
             const paramName = param.slice(1, param.length - 1);
             const index = schema.parameters.findIndex(
-              (x) => x.in === "param" && x.name === paramName
+              (x) => {
+                if ("$ref" in x) {
+                  const pos = x.$ref.split("/").pop();
+                  if (pos) {
+                    const param2 = ctx.components.parameters?.[pos];
+                    if (param2 && !("$ref" in param2)) {
+                      return param2.in === "path" && param2.name === paramName;
+                    }
+                  }
+                  return false;
+                }
+                return x.in === "path" && x.name === paramName;
+              }
             );
-            if (index !== -1) schema.parameters[index].in = "path";
-            else {
+            if (index === -1) {
               schema.parameters.push({
                 schema: { type: "string" },
                 in: "path",
@@ -200,20 +210,24 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     }
   };
   const _documentation = ctx.options.documentation ?? {};
-  const schema = await generatePaths(hono, ctx);
-  for (const path in schema) {
-    for (const method in schema[path]) {
+  const paths = await generatePaths(hono, ctx);
+  for (const path in paths) {
+    for (const method in paths[path]) {
       const isHidden = getHiddenValue({
-        valueOrFunc: schema[path][method]?.hide,
+        valueOrFunc: paths[path][method]?.hide,
         method,
         path,
         c
       });
       if (isHidden) {
-        delete schema[path][method];
+        paths[path][method] = void 0;
       }
     }
   }
+  const components = mergeComponentsObjects(
+    _documentation.components,
+    ctx.components
+  );
   return {
     openapi: "3.1.0",
     ..._documentation,
@@ -227,22 +241,17 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       ..._documentation.info
     },
     paths: {
-      ...removeExcludedPaths(schema, ctx),
+      ...removeExcludedPaths(paths, ctx),
       ..._documentation.paths
     },
-    components: {
-      ..._documentation.components,
-      schemas: {
-        ...ctx.components.schemas,
-        ..._documentation.components?.schemas
-      }
-    }
+    components
   };
 }
 async function generatePaths(hono, ctx) {
   const paths = {};
   for (const route of hono.routes) {
-    if (!(uniqueSymbol in route.handler)) {
+    const middlewareHandler = route.handler[uniqueSymbol];
+    if (!middlewareHandler) {
       if (ctx.options.includeEmptyPaths) {
         registerSchemaPath({
           route,
@@ -260,20 +269,12 @@ async function generatePaths(hono, ctx) {
         continue;
       }
     }
-    const middlewareHandler = route.handler[uniqueSymbol];
     const defaultOptionsForThisMethod = ctx.options.defaultOptions?.[routeMethod];
     const { schema: routeSpecs, components = {} } = await getSpec(
       middlewareHandler,
       defaultOptionsForThisMethod
     );
-    ctx.components = {
-      ...ctx.components,
-      ...components,
-      schemas: {
-        ...ctx.components.schemas,
-        ...components.schemas
-      }
-    };
+    ctx.components = mergeComponentsObjects(ctx.components, components);
     registerSchemaPath({
       route,
       specs: routeSpecs,
@@ -287,14 +288,9 @@ function getHiddenValue(options) {
   if (valueOrFunc != null) {
     if (typeof valueOrFunc === "boolean") {
       return valueOrFunc;
-    } else if (typeof valueOrFunc === "function") {
-      if (c) {
-        return valueOrFunc(c);
-      } else {
-        console.warn(
-          `'c' is not defined, cannot evaluate hide function for ${method} ${path}`
-        );
-      }
+    }
+    if (typeof valueOrFunc === "function") {
+      return valueOrFunc({ c, method, path });
     }
   }
   return false;
@@ -318,7 +314,7 @@ async function getSpec(middlewareHandler, defaultOptions) {
           const raw = response.content?.[contentKey];
           if (!raw) continue;
           if (raw.schema && "toOpenAPISchema" in raw.schema) {
-            const result2 = await raw.schema.toOpenAPISchema(defaultOptions);
+            const result2 = await raw.schema.toOpenAPISchema();
             raw.schema = result2.schema;
             if (result2.components) {
               components = {
@@ -335,7 +331,7 @@ async function getSpec(middlewareHandler, defaultOptions) {
   const result = await middlewareHandler.toOpenAPISchema();
   const docs = {};
   if (middlewareHandler.target === "form" || middlewareHandler.target === "json") {
-    const 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 = {
         content: {
@@ -350,39 +346,78 @@ async function getSpec(middlewareHandler, defaultOptions) {
       };
     }
   } else {
-    const parameters = [];
+    let parameters = [];
     if ("$ref" in result.schema) {
-      parameters.push({
-        in: middlewareHandler.target,
-        // @ts-expect-error
-        name: result.schema.$ref,
-        // @ts-expect-error
-        schema: result.schema
-      });
-    } else {
-      for (const [key, value] of Object.entries(
-        result.schema.properties ?? {}
-      )) {
+      const ref = result.schema.$ref;
+      const pos = ref.split("/").pop();
+      if (pos && result.components?.schemas?.[pos]) {
+        const schema = result.components.schemas[pos];
+        const newParameters = generateParameters(
+          middlewareHandler.target,
+          schema
+        )[0];
+        if (!result.components.parameters) {
+          result.components.parameters = {};
+        }
+        result.components.parameters[pos] = newParameters;
+        delete result.components.schemas[pos];
         parameters.push({
-          in: middlewareHandler.target,
-          name: key,
-          // @ts-expect-error
-          schema: value,
-          required: result.schema.required?.includes(key)
+          $ref: `#/components/parameters/${pos}`
         });
       }
+    } else {
+      parameters = generateParameters(middlewareHandler.target, result.schema);
     }
     docs.parameters = parameters;
   }
   return { schema: docs, components: result.components };
 }
+function generateParameters(target, schema) {
+  const parameters = [];
+  for (const [key, value] of Object.entries(schema.properties ?? {})) {
+    const def = {
+      in: target === "param" ? "path" : target,
+      name: key,
+      // @ts-expect-error
+      schema: value,
+      required: schema.required?.includes(key)
+    };
+    if (def.schema && "description" in def.schema && def.schema.description) {
+      def.description = def.schema.description;
+      def.schema.description = void 0;
+    }
+    parameters.push(def);
+  }
+  return parameters;
+}
+function mergeComponentsObjects(...components) {
+  return components.reduce(
+    (prev, component, index) => {
+      if (!component || index === 0) return prev;
+      if (prev.schemas && Object.keys(prev.schemas).length > 0 || component.schemas && Object.keys(component.schemas).length > 0) {
+        prev.schemas = {
+          ...prev.schemas,
+          ...component.schemas
+        };
+      }
+      if (prev.parameters && Object.keys(prev.parameters).length > 0 || component.parameters && Object.keys(component.parameters).length > 0) {
+        prev.parameters = {
+          ...prev.parameters,
+          ...component.parameters
+        };
+      }
+      return prev;
+    },
+    components[0] ?? {}
+  );
+}
 
-function resolver(schema) {
+function resolver(schema, options) {
   return {
     vendor: schema["~standard"].vendor,
     validate: schema["~standard"].validate,
-    toJSONSchema: (options) => toJsonSchema(schema, options),
-    toOpenAPISchema: (options) => toOpenAPISchema(schema, options)
+    toJSONSchema: () => toJsonSchema(schema, options),
+    toOpenAPISchema: () => toOpenAPISchema(schema, options)
   };
 }
 function validator(target, schema, hook, options) {
@@ -390,7 +425,7 @@ function validator(target, schema, hook, options) {
   return Object.assign(middleware, {
     [uniqueSymbol]: {
       target,
-      ...resolver(schema),
+      ...resolver(schema, options),
       options
     }
   });
@@ -405,16 +440,17 @@ function describeRoute(spec) {
     }
   });
 }
-function describeResponse(handler, responses) {
+function describeResponse(handler, responses, options) {
   const _responses = Object.entries(responses).reduce(
     (acc, [statusCode, response]) => {
       if (response.content) {
         const content = Object.entries(response.content).reduce(
           (contentAcc, [mediaType, media]) => {
             if (media.vSchema) {
+              const { vSchema, ...rest } = media;
               contentAcc[mediaType] = {
-                ...media,
-                schema: resolver(media.vSchema)
+                ...rest,
+                schema: resolver(vSchema, options)
               };
             } else {
               contentAcc[mediaType] = media;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hono-openapi",
   "description": "OpenAPI schema generator for Hono",
-  "version": "0.5.0-rc.3",
+  "version": "1.0.0",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -44,7 +44,7 @@
   "peerDependencies": {
     "@hono/standard-validator": "^0.1.2",
     "@sinclair/typebox": "^0.34.9",
-    "@standard-community/standard-json": "^0.3.0-rc.3",
+    "@standard-community/standard-json": "^0.3.0-rc.4",
     "@standard-community/standard-openapi": "^0.2.0-rc.1",
     "@types/json-schema": "^7.0.15",
     "arktype": "^2.0.0",
@@ -83,7 +83,8 @@
     "@valibot/to-json-schema": "^1.3.0",
     "pkgroll": "^2.13.1",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod-openapi": "4"
   },
   "scripts": {
     "build": "pkgroll --clean-dist",