hono-openapi 1.3.3 → 1.3.5

package/dist/index.cjs

@@ -5,7 +5,7 @@ var standardValidator = require('@hono/standard-validator');
 var standardJson = require('@standard-community/standard-json');
 var standardOpenapi = require('@standard-community/standard-openapi');
 
-const uniqueSymbol = Symbol("openapi");
+const uniqueSymbol = Symbol.for("hono-openapi");
 const VALIDATION_MARKER = "__HonoOpenAPIValidator__";
 const ALLOWED_METHODS = [
   "GET",
@@ -55,6 +55,9 @@ 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, pathContext) {
   const context = [];
@@ -84,7 +87,7 @@ function mergeRequestBodies(previous, current) {
   };
 }
 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)) {
@@ -126,6 +129,8 @@ function mergeSpecs(route, ...specs) {
       operationId: generateOperationId(route)
     }
   );
+  setSpecComponents(merged, specs.flatMap(getSpecComponents));
+  return merged;
 }
 function registerSchemaPath({ route, specs, paths }, pathContext = specsByPathContext) {
   const path = toOpenAPIPath(route.path);
@@ -240,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: {},
@@ -309,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",
@@ -327,7 +382,7 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       ...documentation.info
     },
     paths: {
-      ...removeExcludedPaths(paths, ctx),
+      ...documentedPaths,
       ...documentation.paths
     },
     components
@@ -366,6 +421,7 @@ async function generatePaths(hono, ctx) {
       ctx.components.parameters
     );
     ctx.components = mergeComponentsObjects(ctx.components, components);
+    setSpecComponents(routeSpecs, [components]);
     registerSchemaPath(
       {
         route,
@@ -719,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

@@ -84,8 +84,10 @@ 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, pathContext?: Map<string, Omit<OpenAPIV3_1.OperationObject<{}>, "operationId" | "requestBody" | "responses"> & {
+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;
@@ -100,6 +102,16 @@ declare function registerSchemaPath({ route, specs, paths }: RegisterSchemaPathO
     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> & {
@@ -271,12 +283,12 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
         };
     };
     components: OpenAPIV3_1.ComponentsObject;
-    openapi: string;
     externalDocs?: openapi_types.OpenAPIV3.ExternalDocumentationObject;
     security?: openapi_types.OpenAPIV3.SecurityRequirementObject[];
     servers?: OpenAPIV3_1.ServerObject[];
+    openapi: string;
     webhooks?: Record<string, OpenAPIV3_1.PathItemObject | OpenAPIV3_1.ReferenceObject>;
     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

@@ -84,8 +84,10 @@ 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, pathContext?: Map<string, Omit<OpenAPIV3_1.OperationObject<{}>, "operationId" | "requestBody" | "responses"> & {
+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;
@@ -100,6 +102,16 @@ declare function registerSchemaPath({ route, specs, paths }: RegisterSchemaPathO
     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> & {
@@ -271,12 +283,12 @@ declare function generateSpecs<E extends Env = BlankEnv, P extends string = stri
         };
     };
     components: OpenAPIV3_1.ComponentsObject;
-    openapi: string;
     externalDocs?: openapi_types.OpenAPIV3.ExternalDocumentationObject;
     security?: openapi_types.OpenAPIV3.SecurityRequirementObject[];
     servers?: OpenAPIV3_1.ServerObject[];
+    openapi: string;
     webhooks?: Record<string, OpenAPIV3_1.PathItemObject | OpenAPIV3_1.ReferenceObject>;
     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

@@ -3,7 +3,7 @@ import { sValidator } from '@hono/standard-validator';
 import { loadVendor as loadVendor$1, toJsonSchema } from '@standard-community/standard-json';
 import { loadVendor as loadVendor$2, toOpenAPISchema } from '@standard-community/standard-openapi';
 
-const uniqueSymbol = Symbol("openapi");
+const uniqueSymbol = Symbol.for("hono-openapi");
 const VALIDATION_MARKER = "__HonoOpenAPIValidator__";
 const ALLOWED_METHODS = [
   "GET",
@@ -53,6 +53,9 @@ 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, pathContext) {
   const context = [];
@@ -82,7 +85,7 @@ function mergeRequestBodies(previous, current) {
   };
 }
 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)) {
@@ -124,6 +127,8 @@ function mergeSpecs(route, ...specs) {
       operationId: generateOperationId(route)
     }
   );
+  setSpecComponents(merged, specs.flatMap(getSpecComponents));
+  return merged;
 }
 function registerSchemaPath({ route, specs, paths }, pathContext = specsByPathContext) {
   const path = toOpenAPIPath(route.path);
@@ -238,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: {},
@@ -307,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",
@@ -325,7 +380,7 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
       ...documentation.info
     },
     paths: {
-      ...removeExcludedPaths(paths, ctx),
+      ...documentedPaths,
       ...documentation.paths
     },
     components
@@ -364,6 +419,7 @@ async function generatePaths(hono, ctx) {
       ctx.components.parameters
     );
     ctx.components = mergeComponentsObjects(ctx.components, components);
+    setSpecComponents(routeSpecs, [components]);
     registerSchemaPath(
       {
         route,
@@ -712,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.3",
+  "version": "1.3.5",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",