@elysiajs/openapi 1.4.2 → 1.4.3

package/bun.lock

@@ -8,7 +8,8 @@
         "@scalar/types": "^0.2.13",
         "@sinclair/typemap": "^0.10.1",
         "@types/bun": "1.2.20",
-        "elysia": "1.4.0",
+        "effect": "^3.17.13",
+        "elysia": "1.4.6",
         "eslint": "9.6.0",
         "openapi-types": "^12.1.3",
         "tsup": "^8.5.0",
@@ -167,6 +168,8 @@
 
     "@sinclair/typemap": ["@sinclair/typemap@0.10.1", "", { "peerDependencies": { "@sinclair/typebox": "^0.34.30", "valibot": "^1.0.0", "zod": "^3.24.1" } }, "sha512-UXR0fhu/n3c9B6lB+SLI5t1eVpt9i9CdDrp2TajRe3LbKiUhCTZN2kSfJhjPnpc3I59jMRIhgew7+0HlMi08mg=="],
 
+    "@standard-schema/spec": ["@standard-schema/spec@1.0.0", "", {}, "sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA=="],
+
     "@tokenizer/inflate": ["@tokenizer/inflate@0.2.7", "", { "dependencies": { "debug": "^4.4.0", "fflate": "^0.8.2", "token-types": "^6.0.0" } }, "sha512-MADQgmZT1eKjp06jpI2yozxaU9uVs4GzzgSL+uEq7bVcJ9V1ZXQkeGNql1fsSI0gMy1vhvNTNbUqrx+pZfJVmg=="],
 
     "@tokenizer/token": ["@tokenizer/token@0.3.0", "", {}, "sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A=="],
@@ -239,7 +242,9 @@
 
     "eastasianwidth": ["eastasianwidth@0.2.0", "", {}, "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA=="],
 
-    "elysia": ["elysia@1.4.0", "", { "dependencies": { "cookie": "^1.0.2", "exact-mirror": "0.2.2", "fast-decode-uri-component": "^1.0.1" }, "optionalDependencies": { "@sinclair/typebox": ">= 0.34.0 < 1", "openapi-types": ">= 12.0.0" }, "peerDependencies": { "file-type": ">= 20.0.0", "typescript": ">= 5.0.0" } }, "sha512-AVEq8cWo7+fdkbUtqVXDZ7uhjjv8K6NE6bt9oSzdocaawsW5VhJP2ArPoRYkWdJPYmS4f2FI5xWF+Tvs98yXVw=="],
+    "effect": ["effect@3.17.13", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "fast-check": "^3.23.1" } }, "sha512-JMz5oBxs/6mu4FP9Csjub4jYMUwMLrp+IzUmSDVIzn2NoeoyOXMl7x1lghfr3dLKWffWrdnv/d8nFFdgrHXPqw=="],
+
+    "elysia": ["elysia@1.4.6", "", { "dependencies": { "cookie": "^1.0.2", "exact-mirror": "0.2.2", "fast-decode-uri-component": "^1.0.1" }, "optionalDependencies": { "@sinclair/typebox": ">= 0.34.0 < 1", "openapi-types": ">= 12.0.0" }, "peerDependencies": { "file-type": ">= 20.0.0", "typescript": ">= 5.0.0" } }, "sha512-u2CorXLPs5ZXyWP+tQR+bgka/lJA4vNpB8lDE2w/sTmdaIwoPQmHEL4J3ai6OAlluWR1kfG7T9gO3EYT9D8viQ=="],
 
     "emoji-regex": ["emoji-regex@9.2.2", "", {}, "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg=="],
 
@@ -265,6 +270,8 @@
 
     "exact-mirror": ["exact-mirror@0.2.2", "", { "peerDependencies": { "@sinclair/typebox": "^0.34.15" }, "optionalPeers": ["@sinclair/typebox"] }, "sha512-CrGe+4QzHZlnrXZVlo/WbUZ4qQZq8C0uATQVGVgXIrNXgHDBBNFD1VRfssRA2C9t3RYvh3MadZSdg2Wy7HBoQA=="],
 
+    "fast-check": ["fast-check@3.23.2", "", { "dependencies": { "pure-rand": "^6.1.0" } }, "sha512-h5+1OzzfCC3Ef7VbtKdcv7zsstUQwUDlYpUTvjeUsJAssPgLn7QzbboPtL5ro04Mq0rPOsMzl7q5hIbRs2wD1A=="],
+
     "fast-decode-uri-component": ["fast-decode-uri-component@1.0.1", "", {}, "sha512-WKgKWg5eUxvRZGwW8FvfbaH7AXSh2cL+3j5fMGzUMCxWBJ3dV3a7Wz8y2f/uQ0e3B6WmodD3oS54jTQ9HVTIIg=="],
 
     "fast-deep-equal": ["fast-deep-equal@3.1.3", "", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
@@ -405,6 +412,8 @@
 
     "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
 
+    "pure-rand": ["pure-rand@6.1.0", "", {}, "sha512-bVWawvoZoBYpp6yIoQtQXHZjmz35RSVHnUOTefl8Vcjr8snTPY1wnpSPMWekcFwbxI6gtmT7rSYPFvz71ldiOA=="],
+
     "queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="],
 
     "readdirp": ["readdirp@4.1.2", "", {}, "sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg=="],

package/dist/cjs/index.d.ts

@@ -1,11 +1,11 @@
 import { Elysia } from 'elysia';
-import type { ElysiaOpenAPIConfig, OpenAPIProvider } from './types';
+import type { ElysiaOpenAPIConfig } from './types';
 /**
  * Plugin for [elysia](https://github.com/elysiajs/elysia) that auto-generate OpenAPI documentation page.
  *
  * @see https://github.com/elysiajs/elysia-swagger
  */
-export declare const openapi: <const Enabled extends boolean = true, const Path extends string = "/openapi", const Provider extends OpenAPIProvider = "scalar">({ enabled, path, provider, specPath, documentation, exclude, swagger, scalar, references, mapJsonSchema }?: ElysiaOpenAPIConfig<Enabled, Path, Provider>) => Elysia<"", {
+export declare const openapi: <const Enabled extends boolean = true, const Path extends string = "/openapi">({ enabled, path, provider, specPath, documentation, exclude, swagger, scalar, references, mapJsonSchema }?: ElysiaOpenAPIConfig<Enabled, Path>) => Elysia<"", {
     decorator: {};
     store: {};
     derive: {};

package/dist/cjs/index.js

@@ -317,12 +317,51 @@ var getPossiblePath = (path) => {
   }
   return paths;
 };
-var isValidSchema = (schema) => typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
+var isValidSchema = (schema) => schema && typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
 var getLoosePath = (path) => {
   if (path.charCodeAt(path.length - 1) === 47)
     return path.slice(0, path.length - 1);
   return path + "/";
 };
+var warnings = {
+  zod4: `import openapi from '@elysiajs/openapi'
+import * as z from 'zod'
+
+openapi({
+  mapJsonSchema: {
+    zod: z.toJSONSchema
+  }
+})`,
+  zod3: `import openapi from '@elysiajs/openapi'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    zod: zodToJsonSchema
+  }
+})`,
+  valibot: `import { toJsonSchema } from '@valibot/to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    valibot: toJsonSchema
+  }
+})`,
+  effect: `import { JSONSchema } from 'effect'
+
+openapi({
+  mapJsonSchema: {
+    effect: JSONSchema.make
+  }
+})`
+};
+var warned = {};
+var unwrapReference = (schema, definitions) => {
+  if (!schema?.$ref) return schema;
+  const name = schema.$ref.slice(schema.$ref.lastIndexOf("/") + 1);
+  if (schema.$ref && definitions[name]) schema = definitions[name];
+  return schema;
+};
 var unwrapSchema = (schema, mapJsonSchema) => {
   if (!schema) return;
   if (typeof schema === "string") schema = toRef(schema);
@@ -331,8 +370,49 @@ var unwrapSchema = (schema, mapJsonSchema) => {
   const vendor = schema["~standard"].vendor;
   if (mapJsonSchema?.[vendor] && typeof mapJsonSchema[vendor] === "function")
     return mapJsonSchema[vendor](schema);
-  if (vendor === "zod" || vendor === "sury")
-    return schema.toJSONSchema?.();
+  switch (vendor) {
+    case "zod":
+      if (warned.zod4 || warned.zod3) break;
+      console.warn(
+        "[@elysiajs/openapi] Zod doesn't provide JSON Schema method on the schema"
+      );
+      if ("_zod" in schema) {
+        warned.zod4 = true;
+        console.warn(
+          "For Zod v4, please provide z.toJSONSchema as follows:\n"
+        );
+        console.warn(warnings.zod4);
+      } else {
+        warned.zod3 = true;
+        console.warn(
+          "For Zod v3, please install zod-to-json-schema package and use it like this:\n"
+        );
+        console.warn(warnings.zod3);
+      }
+      break;
+    case "valibot":
+      if (warned.valibot) break;
+      warned.valibot = true;
+      console.warn(
+        "[@elysiajs/openapi] Valibot require a separate package for JSON Schema conversion"
+      );
+      console.warn(
+        "Please install @valibot/to-json-schema package and use it like this:\n"
+      );
+      console.warn(warnings.valibot);
+      break;
+    case "effect":
+      if (warned.effect) break;
+      warned.effect = true;
+      console.warn(
+        "[@elysiajs/openapi] Effect Schema doesn't provide JSON Schema method on the schema"
+      );
+      console.warn(
+        "please provide JSONSchema from 'effect' package as follows:\n"
+      );
+      console.warn(warnings.effect);
+      break;
+  }
   if (vendor === "arktype")
     return schema?.toJsonSchema?.();
   return schema.toJSONSchema?.() ?? schema?.toJsonSchema?.();
@@ -345,6 +425,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
   } = exclude ?? {};
   const excludePaths = Array.isArray(exclude?.paths) ? exclude.paths : typeof exclude?.paths !== "undefined" ? [exclude.paths] : [];
   const paths = /* @__PURE__ */ Object.create(null);
+  const definitions = app.getGlobalDefinitions?.().type;
   const routes = app.getGlobalRoutes();
   if (references) {
     if (!Array.isArray(references)) references = [references];
@@ -359,7 +440,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     if (excludeStaticFile && route.path.includes(".") || excludePaths.includes(route.path) || excludeMethods.includes(method))
       continue;
     const hooks = route.hooks ?? {};
-    if (references)
+    if (references?.length)
       for (const reference of references) {
         if (!reference) continue;
         const refer = reference[route.path]?.[method] ?? reference[getLoosePath(route.path)]?.[method];
@@ -390,7 +471,10 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     };
     const parameters = [];
     if (hooks.params) {
-      const params = unwrapSchema(hooks.params, vendors);
+      const params = unwrapReference(
+        unwrapSchema(hooks.params, vendors),
+        definitions
+      );
       if (params && params.type === "object" && params.properties)
         for (const [paramName, paramSchema] of Object.entries(
           params.properties
@@ -404,7 +488,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
           });
     }
     if (hooks.query) {
-      let query = unwrapSchema(hooks.query, vendors);
+      const query = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (query && query.type === "object" && query.properties) {
         const required = query.required || [];
         for (const [queryName, querySchema] of Object.entries(
@@ -419,7 +503,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.headers) {
-      const headers = unwrapSchema(hooks.query, vendors);
+      const headers = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (headers && headers.type === "object" && headers.properties) {
         const required = headers.required || [];
         for (const [headerName, headerSchema] of Object.entries(
@@ -434,7 +518,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.cookie) {
-      const cookie = unwrapSchema(hooks.cookie, vendors);
+      const cookie = unwrapReference(unwrapSchema(hooks.cookie, vendors), definitions);
       if (cookie && cookie.type === "object" && cookie.properties) {
         const required = cookie.required || [];
         for (const [cookieName, cookieSchema] of Object.entries(
@@ -578,10 +662,9 @@ function toOpenAPISchema(app, exclude, references, vendors) {
         };
     }
   }
-  const _schemas = app.getGlobalDefinitions?.().type;
   const schemas = /* @__PURE__ */ Object.create(null);
-  if (_schemas)
-    for (const [name, schema] of Object.entries(_schemas)) {
+  if (definitions)
+    for (const [name, schema] of Object.entries(definitions)) {
       const jsonSchema = unwrapSchema(schema, vendors);
       if (jsonSchema) schemas[name] = jsonSchema;
     }
@@ -684,6 +767,10 @@ var openapi = ({
       };
     },
     {
+      error({ error }) {
+        console.log("[@elysiajs/openapi] error at specPath");
+        console.warn(error);
+      },
       detail: {
         hide: true
       }

package/dist/cjs/openapi.js

@@ -60,12 +60,51 @@ var getPossiblePath = (path) => {
   }
   return paths;
 };
-var isValidSchema = (schema) => typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
+var isValidSchema = (schema) => schema && typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
 var getLoosePath = (path) => {
   if (path.charCodeAt(path.length - 1) === 47)
     return path.slice(0, path.length - 1);
   return path + "/";
 };
+var warnings = {
+  zod4: `import openapi from '@elysiajs/openapi'
+import * as z from 'zod'
+
+openapi({
+  mapJsonSchema: {
+    zod: z.toJSONSchema
+  }
+})`,
+  zod3: `import openapi from '@elysiajs/openapi'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    zod: zodToJsonSchema
+  }
+})`,
+  valibot: `import { toJsonSchema } from '@valibot/to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    valibot: toJsonSchema
+  }
+})`,
+  effect: `import { JSONSchema } from 'effect'
+
+openapi({
+  mapJsonSchema: {
+    effect: JSONSchema.make
+  }
+})`
+};
+var warned = {};
+var unwrapReference = (schema, definitions) => {
+  if (!schema?.$ref) return schema;
+  const name = schema.$ref.slice(schema.$ref.lastIndexOf("/") + 1);
+  if (schema.$ref && definitions[name]) schema = definitions[name];
+  return schema;
+};
 var unwrapSchema = (schema, mapJsonSchema) => {
   if (!schema) return;
   if (typeof schema === "string") schema = toRef(schema);
@@ -74,8 +113,49 @@ var unwrapSchema = (schema, mapJsonSchema) => {
   const vendor = schema["~standard"].vendor;
   if (mapJsonSchema?.[vendor] && typeof mapJsonSchema[vendor] === "function")
     return mapJsonSchema[vendor](schema);
-  if (vendor === "zod" || vendor === "sury")
-    return schema.toJSONSchema?.();
+  switch (vendor) {
+    case "zod":
+      if (warned.zod4 || warned.zod3) break;
+      console.warn(
+        "[@elysiajs/openapi] Zod doesn't provide JSON Schema method on the schema"
+      );
+      if ("_zod" in schema) {
+        warned.zod4 = true;
+        console.warn(
+          "For Zod v4, please provide z.toJSONSchema as follows:\n"
+        );
+        console.warn(warnings.zod4);
+      } else {
+        warned.zod3 = true;
+        console.warn(
+          "For Zod v3, please install zod-to-json-schema package and use it like this:\n"
+        );
+        console.warn(warnings.zod3);
+      }
+      break;
+    case "valibot":
+      if (warned.valibot) break;
+      warned.valibot = true;
+      console.warn(
+        "[@elysiajs/openapi] Valibot require a separate package for JSON Schema conversion"
+      );
+      console.warn(
+        "Please install @valibot/to-json-schema package and use it like this:\n"
+      );
+      console.warn(warnings.valibot);
+      break;
+    case "effect":
+      if (warned.effect) break;
+      warned.effect = true;
+      console.warn(
+        "[@elysiajs/openapi] Effect Schema doesn't provide JSON Schema method on the schema"
+      );
+      console.warn(
+        "please provide JSONSchema from 'effect' package as follows:\n"
+      );
+      console.warn(warnings.effect);
+      break;
+  }
   if (vendor === "arktype")
     return schema?.toJsonSchema?.();
   return schema.toJSONSchema?.() ?? schema?.toJsonSchema?.();
@@ -88,6 +168,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
   } = exclude ?? {};
   const excludePaths = Array.isArray(exclude?.paths) ? exclude.paths : typeof exclude?.paths !== "undefined" ? [exclude.paths] : [];
   const paths = /* @__PURE__ */ Object.create(null);
+  const definitions = app.getGlobalDefinitions?.().type;
   const routes = app.getGlobalRoutes();
   if (references) {
     if (!Array.isArray(references)) references = [references];
@@ -102,7 +183,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     if (excludeStaticFile && route.path.includes(".") || excludePaths.includes(route.path) || excludeMethods.includes(method))
       continue;
     const hooks = route.hooks ?? {};
-    if (references)
+    if (references?.length)
       for (const reference of references) {
         if (!reference) continue;
         const refer = reference[route.path]?.[method] ?? reference[getLoosePath(route.path)]?.[method];
@@ -133,7 +214,10 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     };
     const parameters = [];
     if (hooks.params) {
-      const params = unwrapSchema(hooks.params, vendors);
+      const params = unwrapReference(
+        unwrapSchema(hooks.params, vendors),
+        definitions
+      );
       if (params && params.type === "object" && params.properties)
         for (const [paramName, paramSchema] of Object.entries(
           params.properties
@@ -147,7 +231,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
           });
     }
     if (hooks.query) {
-      let query = unwrapSchema(hooks.query, vendors);
+      const query = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (query && query.type === "object" && query.properties) {
         const required = query.required || [];
         for (const [queryName, querySchema] of Object.entries(
@@ -162,7 +246,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.headers) {
-      const headers = unwrapSchema(hooks.query, vendors);
+      const headers = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (headers && headers.type === "object" && headers.properties) {
         const required = headers.required || [];
         for (const [headerName, headerSchema] of Object.entries(
@@ -177,7 +261,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.cookie) {
-      const cookie = unwrapSchema(hooks.cookie, vendors);
+      const cookie = unwrapReference(unwrapSchema(hooks.cookie, vendors), definitions);
       if (cookie && cookie.type === "object" && cookie.properties) {
         const required = cookie.required || [];
         for (const [cookieName, cookieSchema] of Object.entries(
@@ -321,10 +405,9 @@ function toOpenAPISchema(app, exclude, references, vendors) {
         };
     }
   }
-  const _schemas = app.getGlobalDefinitions?.().type;
   const schemas = /* @__PURE__ */ Object.create(null);
-  if (_schemas)
-    for (const [name, schema] of Object.entries(_schemas)) {
+  if (definitions)
+    for (const [name, schema] of Object.entries(definitions)) {
       const jsonSchema = unwrapSchema(schema, vendors);
       if (jsonSchema) schemas[name] = jsonSchema;
     }

package/dist/cjs/types.d.ts

@@ -6,6 +6,8 @@ export type OpenAPIProvider = 'scalar' | 'swagger-ui' | null;
 type MaybeArray<T> = T | T[];
 export type MapJsonSchema = {
     [vendor: string]: Function;
+} & {
+    [vendor in 'zod' | 'effect' | 'valibot' | 'arktype' | 'typemap' | 'yup' | 'joi']?: Function;
 };
 export type AdditionalReference = {
     [path in string]: {
@@ -21,7 +23,7 @@ export type AdditionalReference = {
     };
 };
 export type AdditionalReferences = MaybeArray<AdditionalReference | undefined | (() => AdditionalReference | undefined)>;
-export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extends string = '/swagger', Provider extends OpenAPIProvider = 'scalar'> {
+export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extends string = '/swagger'> {
     /**
      * @default true
      */
@@ -67,7 +69,7 @@ export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extend
      * @see https://github.com/scalar/scalar
      * @see https://github.com/swagger-api/swagger-ui
      */
-    provider?: Provider;
+    provider?: OpenAPIProvider;
     /**
      * Additional reference for each endpoint
      */
@@ -81,7 +83,7 @@ export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extend
      * import { toJsonSchema } from '@valibot/to-json-schema'
      *
      * openapi({
-     * 	vendors: {
+     * 	mapJsonSchema: {
      * 	  valibot: toJsonSchema
      *   }
      * })

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { Elysia } from 'elysia';
-import type { ElysiaOpenAPIConfig, OpenAPIProvider } from './types';
+import type { ElysiaOpenAPIConfig } from './types';
 /**
  * Plugin for [elysia](https://github.com/elysiajs/elysia) that auto-generate OpenAPI documentation page.
  *
  * @see https://github.com/elysiajs/elysia-swagger
  */
-export declare const openapi: <const Enabled extends boolean = true, const Path extends string = "/openapi", const Provider extends OpenAPIProvider = "scalar">({ enabled, path, provider, specPath, documentation, exclude, swagger, scalar, references, mapJsonSchema }?: ElysiaOpenAPIConfig<Enabled, Path, Provider>) => Elysia<"", {
+export declare const openapi: <const Enabled extends boolean = true, const Path extends string = "/openapi">({ enabled, path, provider, specPath, documentation, exclude, swagger, scalar, references, mapJsonSchema }?: ElysiaOpenAPIConfig<Enabled, Path>) => Elysia<"", {
     decorator: {};
     store: {};
     derive: {};

package/dist/index.mjs

@@ -290,12 +290,51 @@ var getPossiblePath = (path) => {
   }
   return paths;
 };
-var isValidSchema = (schema) => typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
+var isValidSchema = (schema) => schema && typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
 var getLoosePath = (path) => {
   if (path.charCodeAt(path.length - 1) === 47)
     return path.slice(0, path.length - 1);
   return path + "/";
 };
+var warnings = {
+  zod4: `import openapi from '@elysiajs/openapi'
+import * as z from 'zod'
+
+openapi({
+  mapJsonSchema: {
+    zod: z.toJSONSchema
+  }
+})`,
+  zod3: `import openapi from '@elysiajs/openapi'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    zod: zodToJsonSchema
+  }
+})`,
+  valibot: `import { toJsonSchema } from '@valibot/to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    valibot: toJsonSchema
+  }
+})`,
+  effect: `import { JSONSchema } from 'effect'
+
+openapi({
+  mapJsonSchema: {
+    effect: JSONSchema.make
+  }
+})`
+};
+var warned = {};
+var unwrapReference = (schema, definitions) => {
+  if (!schema?.$ref) return schema;
+  const name = schema.$ref.slice(schema.$ref.lastIndexOf("/") + 1);
+  if (schema.$ref && definitions[name]) schema = definitions[name];
+  return schema;
+};
 var unwrapSchema = (schema, mapJsonSchema) => {
   if (!schema) return;
   if (typeof schema === "string") schema = toRef(schema);
@@ -304,8 +343,49 @@ var unwrapSchema = (schema, mapJsonSchema) => {
   const vendor = schema["~standard"].vendor;
   if (mapJsonSchema?.[vendor] && typeof mapJsonSchema[vendor] === "function")
     return mapJsonSchema[vendor](schema);
-  if (vendor === "zod" || vendor === "sury")
-    return schema.toJSONSchema?.();
+  switch (vendor) {
+    case "zod":
+      if (warned.zod4 || warned.zod3) break;
+      console.warn(
+        "[@elysiajs/openapi] Zod doesn't provide JSON Schema method on the schema"
+      );
+      if ("_zod" in schema) {
+        warned.zod4 = true;
+        console.warn(
+          "For Zod v4, please provide z.toJSONSchema as follows:\n"
+        );
+        console.warn(warnings.zod4);
+      } else {
+        warned.zod3 = true;
+        console.warn(
+          "For Zod v3, please install zod-to-json-schema package and use it like this:\n"
+        );
+        console.warn(warnings.zod3);
+      }
+      break;
+    case "valibot":
+      if (warned.valibot) break;
+      warned.valibot = true;
+      console.warn(
+        "[@elysiajs/openapi] Valibot require a separate package for JSON Schema conversion"
+      );
+      console.warn(
+        "Please install @valibot/to-json-schema package and use it like this:\n"
+      );
+      console.warn(warnings.valibot);
+      break;
+    case "effect":
+      if (warned.effect) break;
+      warned.effect = true;
+      console.warn(
+        "[@elysiajs/openapi] Effect Schema doesn't provide JSON Schema method on the schema"
+      );
+      console.warn(
+        "please provide JSONSchema from 'effect' package as follows:\n"
+      );
+      console.warn(warnings.effect);
+      break;
+  }
   if (vendor === "arktype")
     return schema?.toJsonSchema?.();
   return schema.toJSONSchema?.() ?? schema?.toJsonSchema?.();
@@ -318,6 +398,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
   } = exclude ?? {};
   const excludePaths = Array.isArray(exclude?.paths) ? exclude.paths : typeof exclude?.paths !== "undefined" ? [exclude.paths] : [];
   const paths = /* @__PURE__ */ Object.create(null);
+  const definitions = app.getGlobalDefinitions?.().type;
   const routes = app.getGlobalRoutes();
   if (references) {
     if (!Array.isArray(references)) references = [references];
@@ -332,7 +413,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     if (excludeStaticFile && route.path.includes(".") || excludePaths.includes(route.path) || excludeMethods.includes(method))
       continue;
     const hooks = route.hooks ?? {};
-    if (references)
+    if (references?.length)
       for (const reference of references) {
         if (!reference) continue;
         const refer = reference[route.path]?.[method] ?? reference[getLoosePath(route.path)]?.[method];
@@ -363,7 +444,10 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     };
     const parameters = [];
     if (hooks.params) {
-      const params = unwrapSchema(hooks.params, vendors);
+      const params = unwrapReference(
+        unwrapSchema(hooks.params, vendors),
+        definitions
+      );
       if (params && params.type === "object" && params.properties)
         for (const [paramName, paramSchema] of Object.entries(
           params.properties
@@ -377,7 +461,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
           });
     }
     if (hooks.query) {
-      let query = unwrapSchema(hooks.query, vendors);
+      const query = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (query && query.type === "object" && query.properties) {
         const required = query.required || [];
         for (const [queryName, querySchema] of Object.entries(
@@ -392,7 +476,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.headers) {
-      const headers = unwrapSchema(hooks.query, vendors);
+      const headers = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (headers && headers.type === "object" && headers.properties) {
         const required = headers.required || [];
         for (const [headerName, headerSchema] of Object.entries(
@@ -407,7 +491,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.cookie) {
-      const cookie = unwrapSchema(hooks.cookie, vendors);
+      const cookie = unwrapReference(unwrapSchema(hooks.cookie, vendors), definitions);
       if (cookie && cookie.type === "object" && cookie.properties) {
         const required = cookie.required || [];
         for (const [cookieName, cookieSchema] of Object.entries(
@@ -551,10 +635,9 @@ function toOpenAPISchema(app, exclude, references, vendors) {
         };
     }
   }
-  const _schemas = app.getGlobalDefinitions?.().type;
   const schemas = /* @__PURE__ */ Object.create(null);
-  if (_schemas)
-    for (const [name, schema] of Object.entries(_schemas)) {
+  if (definitions)
+    for (const [name, schema] of Object.entries(definitions)) {
       const jsonSchema = unwrapSchema(schema, vendors);
       if (jsonSchema) schemas[name] = jsonSchema;
     }
@@ -657,6 +740,10 @@ var openapi = ({
       };
     },
     {
+      error({ error }) {
+        console.log("[@elysiajs/openapi] error at specPath");
+        console.warn(error);
+      },
       detail: {
         hide: true
       }

package/dist/openapi.mjs

@@ -31,12 +31,51 @@ var getPossiblePath = (path) => {
   }
   return paths;
 };
-var isValidSchema = (schema) => typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
+var isValidSchema = (schema) => schema && typeof schema === "object" && (Kind in schema && schema[Kind] !== "Unknown" || schema.type || schema.properties || schema.items);
 var getLoosePath = (path) => {
   if (path.charCodeAt(path.length - 1) === 47)
     return path.slice(0, path.length - 1);
   return path + "/";
 };
+var warnings = {
+  zod4: `import openapi from '@elysiajs/openapi'
+import * as z from 'zod'
+
+openapi({
+  mapJsonSchema: {
+    zod: z.toJSONSchema
+  }
+})`,
+  zod3: `import openapi from '@elysiajs/openapi'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    zod: zodToJsonSchema
+  }
+})`,
+  valibot: `import { toJsonSchema } from '@valibot/to-json-schema'
+
+openapi({
+  mapJsonSchema: {
+    valibot: toJsonSchema
+  }
+})`,
+  effect: `import { JSONSchema } from 'effect'
+
+openapi({
+  mapJsonSchema: {
+    effect: JSONSchema.make
+  }
+})`
+};
+var warned = {};
+var unwrapReference = (schema, definitions) => {
+  if (!schema?.$ref) return schema;
+  const name = schema.$ref.slice(schema.$ref.lastIndexOf("/") + 1);
+  if (schema.$ref && definitions[name]) schema = definitions[name];
+  return schema;
+};
 var unwrapSchema = (schema, mapJsonSchema) => {
   if (!schema) return;
   if (typeof schema === "string") schema = toRef(schema);
@@ -45,8 +84,49 @@ var unwrapSchema = (schema, mapJsonSchema) => {
   const vendor = schema["~standard"].vendor;
   if (mapJsonSchema?.[vendor] && typeof mapJsonSchema[vendor] === "function")
     return mapJsonSchema[vendor](schema);
-  if (vendor === "zod" || vendor === "sury")
-    return schema.toJSONSchema?.();
+  switch (vendor) {
+    case "zod":
+      if (warned.zod4 || warned.zod3) break;
+      console.warn(
+        "[@elysiajs/openapi] Zod doesn't provide JSON Schema method on the schema"
+      );
+      if ("_zod" in schema) {
+        warned.zod4 = true;
+        console.warn(
+          "For Zod v4, please provide z.toJSONSchema as follows:\n"
+        );
+        console.warn(warnings.zod4);
+      } else {
+        warned.zod3 = true;
+        console.warn(
+          "For Zod v3, please install zod-to-json-schema package and use it like this:\n"
+        );
+        console.warn(warnings.zod3);
+      }
+      break;
+    case "valibot":
+      if (warned.valibot) break;
+      warned.valibot = true;
+      console.warn(
+        "[@elysiajs/openapi] Valibot require a separate package for JSON Schema conversion"
+      );
+      console.warn(
+        "Please install @valibot/to-json-schema package and use it like this:\n"
+      );
+      console.warn(warnings.valibot);
+      break;
+    case "effect":
+      if (warned.effect) break;
+      warned.effect = true;
+      console.warn(
+        "[@elysiajs/openapi] Effect Schema doesn't provide JSON Schema method on the schema"
+      );
+      console.warn(
+        "please provide JSONSchema from 'effect' package as follows:\n"
+      );
+      console.warn(warnings.effect);
+      break;
+  }
   if (vendor === "arktype")
     return schema?.toJsonSchema?.();
   return schema.toJSONSchema?.() ?? schema?.toJsonSchema?.();
@@ -59,6 +139,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
   } = exclude ?? {};
   const excludePaths = Array.isArray(exclude?.paths) ? exclude.paths : typeof exclude?.paths !== "undefined" ? [exclude.paths] : [];
   const paths = /* @__PURE__ */ Object.create(null);
+  const definitions = app.getGlobalDefinitions?.().type;
   const routes = app.getGlobalRoutes();
   if (references) {
     if (!Array.isArray(references)) references = [references];
@@ -73,7 +154,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     if (excludeStaticFile && route.path.includes(".") || excludePaths.includes(route.path) || excludeMethods.includes(method))
       continue;
     const hooks = route.hooks ?? {};
-    if (references)
+    if (references?.length)
       for (const reference of references) {
         if (!reference) continue;
         const refer = reference[route.path]?.[method] ?? reference[getLoosePath(route.path)]?.[method];
@@ -104,7 +185,10 @@ function toOpenAPISchema(app, exclude, references, vendors) {
     };
     const parameters = [];
     if (hooks.params) {
-      const params = unwrapSchema(hooks.params, vendors);
+      const params = unwrapReference(
+        unwrapSchema(hooks.params, vendors),
+        definitions
+      );
       if (params && params.type === "object" && params.properties)
         for (const [paramName, paramSchema] of Object.entries(
           params.properties
@@ -118,7 +202,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
           });
     }
     if (hooks.query) {
-      let query = unwrapSchema(hooks.query, vendors);
+      const query = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (query && query.type === "object" && query.properties) {
         const required = query.required || [];
         for (const [queryName, querySchema] of Object.entries(
@@ -133,7 +217,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.headers) {
-      const headers = unwrapSchema(hooks.query, vendors);
+      const headers = unwrapReference(unwrapSchema(hooks.query, vendors), definitions);
       if (headers && headers.type === "object" && headers.properties) {
         const required = headers.required || [];
         for (const [headerName, headerSchema] of Object.entries(
@@ -148,7 +232,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     if (hooks.cookie) {
-      const cookie = unwrapSchema(hooks.cookie, vendors);
+      const cookie = unwrapReference(unwrapSchema(hooks.cookie, vendors), definitions);
       if (cookie && cookie.type === "object" && cookie.properties) {
         const required = cookie.required || [];
         for (const [cookieName, cookieSchema] of Object.entries(
@@ -292,10 +376,9 @@ function toOpenAPISchema(app, exclude, references, vendors) {
         };
     }
   }
-  const _schemas = app.getGlobalDefinitions?.().type;
   const schemas = /* @__PURE__ */ Object.create(null);
-  if (_schemas)
-    for (const [name, schema] of Object.entries(_schemas)) {
+  if (definitions)
+    for (const [name, schema] of Object.entries(definitions)) {
       const jsonSchema = unwrapSchema(schema, vendors);
       if (jsonSchema) schemas[name] = jsonSchema;
     }

package/dist/types.d.ts

@@ -6,6 +6,8 @@ export type OpenAPIProvider = 'scalar' | 'swagger-ui' | null;
 type MaybeArray<T> = T | T[];
 export type MapJsonSchema = {
     [vendor: string]: Function;
+} & {
+    [vendor in 'zod' | 'effect' | 'valibot' | 'arktype' | 'typemap' | 'yup' | 'joi']?: Function;
 };
 export type AdditionalReference = {
     [path in string]: {
@@ -21,7 +23,7 @@ export type AdditionalReference = {
     };
 };
 export type AdditionalReferences = MaybeArray<AdditionalReference | undefined | (() => AdditionalReference | undefined)>;
-export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extends string = '/swagger', Provider extends OpenAPIProvider = 'scalar'> {
+export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extends string = '/swagger'> {
     /**
      * @default true
      */
@@ -67,7 +69,7 @@ export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extend
      * @see https://github.com/scalar/scalar
      * @see https://github.com/swagger-api/swagger-ui
      */
-    provider?: Provider;
+    provider?: OpenAPIProvider;
     /**
      * Additional reference for each endpoint
      */
@@ -81,7 +83,7 @@ export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extend
      * import { toJsonSchema } from '@valibot/to-json-schema'
      *
      * openapi({
-     * 	vendors: {
+     * 	mapJsonSchema: {
      * 	  valibot: toJsonSchema
      *   }
      * })

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@elysiajs/openapi",
-    "version": "1.4.2",
+    "version": "1.4.3",
     "description": "Plugin for Elysia to auto-generate API documentation",
     "author": {
         "name": "saltyAom",
@@ -79,7 +79,8 @@
         "@scalar/types": "^0.2.13",
         "@sinclair/typemap": "^0.10.1",
         "@types/bun": "1.2.20",
-        "elysia": "1.4.0",
+        "effect": "^3.17.13",
+        "elysia": "1.4.6",
         "eslint": "9.6.0",
         "openapi-types": "^12.1.3",
         "tsup": "^8.5.0",