hono-openapi 1.0.8 → 1.1.1

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/hono-openapi.svg)](https://npmjs.org/package/hono-openapi "View this project on NPM")
 [![npm downloads](https://img.shields.io/npm/dm/hono-openapi)](https://www.npmjs.com/package/hono-openapi)
 
-This can automatically generate the OpenAPI specification for the Hono API using your validation schema, which can be used to generate client libraries, documentation, and more.
+This can automatically generate the OpenAPI specification for the Hono App using your validation schema, which can be used to generate client libraries, documentation, and more.
 
 This lib supports all the validation libs which are [Standard Schema](https://standardschema.dev/) compliant.
 
@@ -19,5 +19,5 @@ Visit our [contributing docs](https://github.com/rhinobase/hono-openapi/blob/mai
 
 ## Credits
 
-- The idea for this project was inspired by [ElysiaJS](https://elysiajs.com/) and their amazing work on generating [OpenAPI](https://elysiajs.com/recipe/openapi.html) specifications.
+- The idea for this project was inspired by [ElysiaJS](https://elysiajs.com/) and their amazing work on generating [OpenAPI](https://elysiajs.com/patterns/openapi) specifications.
 - This project would not have been possible without the work of [Sam Chung](https://github.com/samchungy) and his [Zod OpenAPI](https://github.com/samchungy/zod-openapi) package.

package/dist/index.cjs

@@ -61,6 +61,9 @@ function getPathContext(path) {
   }
   return context;
 }
+function clearSpecsContext() {
+  specsByPathContext.clear();
+}
 function mergeSpecs(route, ...specs) {
   return specs.reduce(
     (prev, spec) => {
@@ -72,6 +75,8 @@ function mergeSpecs(route, ...specs) {
             const values = [...prev[key] ?? [], ...value];
             if (key === "tags") {
               prev[key] = Array.from(new Set(values));
+            } else if (key === "parameters") {
+              prev[key] = mergeParameters(values);
             } else {
               prev[key] = values;
             }
@@ -133,57 +138,65 @@ function removeExcludedPaths(paths, ctx) {
   const newPaths = {};
   const _exclude = Array.isArray(exclude) ? exclude : [exclude];
   for (const [key, value] of Object.entries(paths)) {
-    const isPathExcluded = !_exclude.some((x) => {
+    if (value == null) continue;
+    const isExplicitlyExcluded = _exclude.some((x) => {
       if (typeof x === "string") return key === x;
       return x.test(key);
     });
-    const isStaticFileExcluded = excludeStaticFile ? !key.includes(".") || key.includes("{") : true;
-    if (isPathExcluded && !(key.includes("*") && !key.includes("{")) && isStaticFileExcluded && value != null) {
-      for (const method of Object.keys(value)) {
-        const schema = value[method];
-        if (schema == null) continue;
-        if (key.includes("{")) {
-          if (!schema.parameters) schema.parameters = [];
-          const pathParameters = key.split("/").filter(
-            (x) => x.startsWith("{") && !schema.parameters.find(
-              (params) => params.in === "path" && params.name === x.slice(1, x.length - 1)
-            )
-          );
-          for (const param of pathParameters) {
-            const paramName = param.slice(1, param.length - 1);
-            const index = schema.parameters.findIndex(
-              (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;
-                    }
+    if (isExplicitlyExcluded) continue;
+    const isWildcardWithoutParameters = key.includes("*") && !key.includes("{");
+    if (isWildcardWithoutParameters) continue;
+    if (excludeStaticFile) {
+      const hasPathParameters = key.includes("{");
+      const lastSegment = key.split("/").pop() || "";
+      const looksLikeStaticFile = lastSegment.includes(".");
+      const shouldExcludeAsStaticFile = !hasPathParameters && looksLikeStaticFile;
+      if (shouldExcludeAsStaticFile) continue;
+    }
+    for (const method of Object.keys(value)) {
+      const schema = value[method];
+      if (schema == null) continue;
+      if (key.includes("{")) {
+        if (!schema.parameters) schema.parameters = [];
+        const pathParameters = key.split("/").filter(
+          (x) => x.startsWith("{") && !schema.parameters.find(
+            (params) => params.in === "path" && params.name === x.slice(1, x.length - 1)
+          )
+        );
+        for (const param of pathParameters) {
+          const paramName = param.slice(1, param.length - 1);
+          const index = schema.parameters.findIndex(
+            (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;
+                return false;
               }
-            );
-            if (index === -1) {
-              schema.parameters.push({
-                schema: { type: "string" },
-                in: "path",
-                name: paramName,
-                required: true
-              });
+              return x.in === "path" && x.name === paramName;
             }
+          );
+          if (index === -1) {
+            schema.parameters.push({
+              schema: { type: "string" },
+              in: "path",
+              name: paramName,
+              required: true
+            });
           }
         }
-        if (!schema.responses) {
-          schema.responses = {
-            200: {}
-          };
-        }
       }
-      newPaths[key] = value;
+      if (!schema.responses) {
+        schema.responses = {
+          200: {}
+        };
+      }
     }
+    newPaths[key] = value;
   }
   return newPaths;
 }
@@ -213,6 +226,7 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     }
   };
   const _documentation = ctx.options.documentation ?? {};
+  clearSpecsContext();
   const paths = await generatePaths(hono, ctx);
   for (const path in paths) {
     for (const method in paths[path]) {
@@ -426,12 +440,12 @@ function loadVendor(vendor, fn) {
     standardOpenapi.loadVendor(vendor, fn.toOpenAPISchema);
   }
 }
-function resolver(schema, options) {
+function resolver(schema, userDefinedOptions) {
   return {
     vendor: schema["~standard"].vendor,
     validate: schema["~standard"].validate,
-    toJSONSchema: () => standardJson.toJsonSchema(schema, options),
-    toOpenAPISchema: () => standardOpenapi.toOpenAPISchema(schema, options)
+    toJSONSchema: (customOptions) => standardJson.toJsonSchema(schema, { ...userDefinedOptions, ...customOptions }),
+    toOpenAPISchema: (customOptions) => standardOpenapi.toOpenAPISchema(schema, { ...userDefinedOptions, ...customOptions })
   };
 }
 function validator(target, schema, hook, options) {
@@ -489,6 +503,7 @@ function describeResponse(handler, responses, options) {
 }
 
 exports.ALLOWED_METHODS = ALLOWED_METHODS;
+exports.clearSpecsContext = clearSpecsContext;
 exports.describeResponse = describeResponse;
 exports.describeRoute = describeRoute;
 exports.generateSpecs = generateSpecs;

package/dist/index.d.cts

@@ -74,11 +74,11 @@ declare function loadVendor(vendor: string, fn: {
  * @param schema Validation schema
  * @returns Resolver result
  */
-declare function resolver<Schema extends StandardSchemaV1>(schema: Schema, options?: Record<string, unknown>): {
+declare function resolver<Schema extends StandardSchemaV1>(schema: Schema, userDefinedOptions?: Record<string, unknown>): {
     vendor: string;
     validate: (value: unknown) => StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;
-    toJSONSchema: () => JSONSchema7 | Promise<JSONSchema7>;
-    toOpenAPISchema: () => Promise<{
+    toJSONSchema: (customOptions?: Record<string, unknown>) => JSONSchema7 | Promise<JSONSchema7>;
+    toOpenAPISchema: (customOptions?: Record<string, unknown>) => Promise<{
         schema: OpenAPIV3_1.SchemaObject;
         components: OpenAPIV3_1.ComponentsObject | undefined;
     }>;
@@ -121,9 +121,9 @@ type ResponseObject<T extends Partial<Record<StatusCode, StandardSchemaV1>>> = {
     });
 };
 type Num<T> = T extends `${infer N extends number}` ? N : T;
-type HandlerResponse<T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>> = {
-    [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 HandlerResponse<T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>> = PromiseOr<{
+    [K in keyof T]: T[K] extends StandardSchemaV1 ? TypedResponse<StandardSchemaV1.InferOutput<T[K]>, Num<K> extends StatusCode ? Num<K> : never> : never;
+}[keyof T]>;
 type Handler<E extends Env, P extends string, I extends Input, 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, P extends string, I extends Input, 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>;
 
@@ -133,6 +133,7 @@ declare function describeResponse<E extends Env, P extends string, I extends Inp
 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 clearSpecsContext(): void;
 declare function registerSchemaPath({ route, specs, paths, }: RegisterSchemaPathOptions): void;
 declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: SpecContext): OpenAPIV3_1.PathsObject<{}, {}>;
 
@@ -164,7 +165,7 @@ type GenerateSpecOptions = {
      */
     includeEmptyPaths: boolean;
     /**
-     * Determine if Swagger should exclude static files.
+     * Determine if Swagger should exclude static files (by checking if the last path segment contains a period).
      *
      * @default true
      */
@@ -276,4 +277,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 SpecContext, describeResponse, describeRoute, generateSpecs, loadVendor, 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, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/dist/index.d.ts

@@ -74,11 +74,11 @@ declare function loadVendor(vendor: string, fn: {
  * @param schema Validation schema
  * @returns Resolver result
  */
-declare function resolver<Schema extends StandardSchemaV1>(schema: Schema, options?: Record<string, unknown>): {
+declare function resolver<Schema extends StandardSchemaV1>(schema: Schema, userDefinedOptions?: Record<string, unknown>): {
     vendor: string;
     validate: (value: unknown) => StandardSchemaV1.Result<unknown> | Promise<StandardSchemaV1.Result<unknown>>;
-    toJSONSchema: () => JSONSchema7 | Promise<JSONSchema7>;
-    toOpenAPISchema: () => Promise<{
+    toJSONSchema: (customOptions?: Record<string, unknown>) => JSONSchema7 | Promise<JSONSchema7>;
+    toOpenAPISchema: (customOptions?: Record<string, unknown>) => Promise<{
         schema: OpenAPIV3_1.SchemaObject;
         components: OpenAPIV3_1.ComponentsObject | undefined;
     }>;
@@ -121,9 +121,9 @@ type ResponseObject<T extends Partial<Record<StatusCode, StandardSchemaV1>>> = {
     });
 };
 type Num<T> = T extends `${infer N extends number}` ? N : T;
-type HandlerResponse<T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>> = {
-    [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 HandlerResponse<T extends Partial<Record<StatusCode, StandardSchemaV1>> = Partial<Record<StatusCode, StandardSchemaV1>>> = PromiseOr<{
+    [K in keyof T]: T[K] extends StandardSchemaV1 ? TypedResponse<StandardSchemaV1.InferOutput<T[K]>, Num<K> extends StatusCode ? Num<K> : never> : never;
+}[keyof T]>;
 type Handler<E extends Env, P extends string, I extends Input, 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, P extends string, I extends Input, 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>;
 
@@ -133,6 +133,7 @@ declare function describeResponse<E extends Env, P extends string, I extends Inp
 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 clearSpecsContext(): void;
 declare function registerSchemaPath({ route, specs, paths, }: RegisterSchemaPathOptions): void;
 declare function removeExcludedPaths(paths: OpenAPIV3_1.PathsObject, ctx: SpecContext): OpenAPIV3_1.PathsObject<{}, {}>;
 
@@ -164,7 +165,7 @@ type GenerateSpecOptions = {
      */
     includeEmptyPaths: boolean;
     /**
-     * Determine if Swagger should exclude static files.
+     * Determine if Swagger should exclude static files (by checking if the last path segment contains a period).
      *
      * @default true
      */
@@ -276,4 +277,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 SpecContext, describeResponse, describeRoute, generateSpecs, loadVendor, 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, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/dist/index.js

@@ -59,6 +59,9 @@ function getPathContext(path) {
   }
   return context;
 }
+function clearSpecsContext() {
+  specsByPathContext.clear();
+}
 function mergeSpecs(route, ...specs) {
   return specs.reduce(
     (prev, spec) => {
@@ -70,6 +73,8 @@ function mergeSpecs(route, ...specs) {
             const values = [...prev[key] ?? [], ...value];
             if (key === "tags") {
               prev[key] = Array.from(new Set(values));
+            } else if (key === "parameters") {
+              prev[key] = mergeParameters(values);
             } else {
               prev[key] = values;
             }
@@ -131,57 +136,65 @@ function removeExcludedPaths(paths, ctx) {
   const newPaths = {};
   const _exclude = Array.isArray(exclude) ? exclude : [exclude];
   for (const [key, value] of Object.entries(paths)) {
-    const isPathExcluded = !_exclude.some((x) => {
+    if (value == null) continue;
+    const isExplicitlyExcluded = _exclude.some((x) => {
       if (typeof x === "string") return key === x;
       return x.test(key);
     });
-    const isStaticFileExcluded = excludeStaticFile ? !key.includes(".") || key.includes("{") : true;
-    if (isPathExcluded && !(key.includes("*") && !key.includes("{")) && isStaticFileExcluded && value != null) {
-      for (const method of Object.keys(value)) {
-        const schema = value[method];
-        if (schema == null) continue;
-        if (key.includes("{")) {
-          if (!schema.parameters) schema.parameters = [];
-          const pathParameters = key.split("/").filter(
-            (x) => x.startsWith("{") && !schema.parameters.find(
-              (params) => params.in === "path" && params.name === x.slice(1, x.length - 1)
-            )
-          );
-          for (const param of pathParameters) {
-            const paramName = param.slice(1, param.length - 1);
-            const index = schema.parameters.findIndex(
-              (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;
-                    }
+    if (isExplicitlyExcluded) continue;
+    const isWildcardWithoutParameters = key.includes("*") && !key.includes("{");
+    if (isWildcardWithoutParameters) continue;
+    if (excludeStaticFile) {
+      const hasPathParameters = key.includes("{");
+      const lastSegment = key.split("/").pop() || "";
+      const looksLikeStaticFile = lastSegment.includes(".");
+      const shouldExcludeAsStaticFile = !hasPathParameters && looksLikeStaticFile;
+      if (shouldExcludeAsStaticFile) continue;
+    }
+    for (const method of Object.keys(value)) {
+      const schema = value[method];
+      if (schema == null) continue;
+      if (key.includes("{")) {
+        if (!schema.parameters) schema.parameters = [];
+        const pathParameters = key.split("/").filter(
+          (x) => x.startsWith("{") && !schema.parameters.find(
+            (params) => params.in === "path" && params.name === x.slice(1, x.length - 1)
+          )
+        );
+        for (const param of pathParameters) {
+          const paramName = param.slice(1, param.length - 1);
+          const index = schema.parameters.findIndex(
+            (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;
+                return false;
               }
-            );
-            if (index === -1) {
-              schema.parameters.push({
-                schema: { type: "string" },
-                in: "path",
-                name: paramName,
-                required: true
-              });
+              return x.in === "path" && x.name === paramName;
             }
+          );
+          if (index === -1) {
+            schema.parameters.push({
+              schema: { type: "string" },
+              in: "path",
+              name: paramName,
+              required: true
+            });
           }
         }
-        if (!schema.responses) {
-          schema.responses = {
-            200: {}
-          };
-        }
       }
-      newPaths[key] = value;
+      if (!schema.responses) {
+        schema.responses = {
+          200: {}
+        };
+      }
     }
+    newPaths[key] = value;
   }
   return newPaths;
 }
@@ -211,6 +224,7 @@ async function generateSpecs(hono, options = DEFAULT_OPTIONS, c) {
     }
   };
   const _documentation = ctx.options.documentation ?? {};
+  clearSpecsContext();
   const paths = await generatePaths(hono, ctx);
   for (const path in paths) {
     for (const method in paths[path]) {
@@ -424,12 +438,12 @@ function loadVendor(vendor, fn) {
     loadVendor$2(vendor, fn.toOpenAPISchema);
   }
 }
-function resolver(schema, options) {
+function resolver(schema, userDefinedOptions) {
   return {
     vendor: schema["~standard"].vendor,
     validate: schema["~standard"].validate,
-    toJSONSchema: () => toJsonSchema(schema, options),
-    toOpenAPISchema: () => toOpenAPISchema(schema, options)
+    toJSONSchema: (customOptions) => toJsonSchema(schema, { ...userDefinedOptions, ...customOptions }),
+    toOpenAPISchema: (customOptions) => toOpenAPISchema(schema, { ...userDefinedOptions, ...customOptions })
   };
 }
 function validator(target, schema, hook, options) {
@@ -486,4 +500,4 @@ function describeResponse(handler, responses, options) {
   });
 }
 
-export { ALLOWED_METHODS, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };
+export { ALLOWED_METHODS, clearSpecsContext, describeResponse, describeRoute, generateSpecs, loadVendor, openAPIRouteHandler, registerSchemaPath, removeExcludedPaths, resolver, uniqueSymbol, validator };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hono-openapi",
   "description": "OpenAPI schema generator for Hono",
-  "version": "1.0.8",
+  "version": "1.1.1",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -25,8 +25,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/rhinobase/hono-openapi.git",
-    "directory": "packages/core"
+    "url": "git+https://github.com/rhinobase/hono-openapi.git"
   },
   "bugs": {
     "url": "https://github.com/rhinobase/hono-openapi/issues"
@@ -43,8 +42,8 @@
   },
   "peerDependencies": {
     "@hono/standard-validator": "^0.1.2",
-    "@standard-community/standard-json": "^0.3.1",
-    "@standard-community/standard-openapi": "^0.2.4",
+    "@standard-community/standard-json": "^0.3.5",
+    "@standard-community/standard-openapi": "^0.2.8",
     "@types/json-schema": "^7.0.15",
     "hono": "^4.8.3",
     "openapi-types": "^12.1.3"
@@ -66,8 +65,11 @@
     "husky": "^9.1.7",
     "is-ci": "^4.1.0",
     "nano-staged": "^0.8.0",
+    "pkg-pr-new": "^0.0.60",
     "pkgroll": "^2.13.1",
+    "typebox": "^1.0.17",
     "typescript": "^5.8.3",
+    "sury": "^10.0.0",
     "valibot": "^1.1.0",
     "vitest": "^3.2.4",
     "zod": "^3.23.8",
@@ -75,6 +77,7 @@
   },
   "scripts": {
     "build": "pkgroll --clean-dist",
+    "lint": "biome check .",
     "format": "biome check --write .",
     "test": "vitest"
   }