@elysiajs/openapi 1.4.9 → 1.4.11

package/dist/cjs/openapi.d.ts

@@ -1,6 +1,6 @@
 import { type AnyElysia, type TSchema, type InputSchema } from 'elysia';
 import type { OpenAPIV3 } from 'openapi-types';
-import { type TProperties } from '@sinclair/typebox';
+import { TAnySchema, type TProperties } from '@sinclair/typebox';
 import type { AdditionalReferences, ElysiaOpenAPIConfig, MapJsonSchema } from './types';
 export declare const capitalize: (word: string) => string;
 /**
@@ -11,6 +11,7 @@ export declare const capitalize: (word: string) => string;
 export declare const getPossiblePath: (path: string) => string[];
 export declare const getLoosePath: (path: string) => string;
 export declare const unwrapSchema: (schema: InputSchema["body"], mapJsonSchema?: MapJsonSchema) => OpenAPIV3.SchemaObject | undefined;
+export declare const enumToOpenApi: <T extends TAnySchema | OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined>(_schema: T) => T;
 /**
  * Converts Elysia routes to OpenAPI 3.0.3 paths schema
  * @param routes Array of Elysia route objects

package/dist/cjs/openapi.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var openapi_exports = {};
 __export(openapi_exports, {
   capitalize: () => capitalize,
+  enumToOpenApi: () => enumToOpenApi,
   getLoosePath: () => getLoosePath,
   getPossiblePath: () => getPossiblePath,
   toOpenAPISchema: () => toOpenAPISchema,
@@ -105,62 +106,98 @@ var unwrapReference = (schema, definitions) => {
   if (!ref) return schema;
   const name = ref.slice(ref.lastIndexOf("/") + 1);
   if (ref && definitions[name]) schema = definitions[name];
-  return schema;
+  return enumToOpenApi(schema);
 };
 var unwrapSchema = (schema, mapJsonSchema) => {
   if (!schema) return;
   if (typeof schema === "string") schema = toRef(schema);
-  if (Kind in schema) return schema;
+  if (Kind in schema) return enumToOpenApi(schema);
   if (Kind in schema || !schema?.["~standard"]) return;
   const vendor = schema["~standard"].vendor;
-  if (mapJsonSchema?.[vendor] && typeof mapJsonSchema[vendor] === "function")
-    return mapJsonSchema[vendor](schema);
-  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;
+  try {
+    if (mapJsonSchema?.[vendor] && typeof mapJsonSchema[vendor] === "function")
+      return enumToOpenApi(mapJsonSchema[vendor](schema));
+    switch (vendor) {
+      case "zod":
+        if (warned.zod4 || warned.zod3) break;
         console.warn(
-          "For Zod v4, please provide z.toJSONSchema as follows:\n"
+          "[@elysiajs/openapi] Zod doesn't provide JSON Schema method on the schema"
         );
-        console.warn(warnings.zod4);
-      } else {
-        warned.zod3 = true;
+        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(
-          "For Zod v3, please install zod-to-json-schema package and use it like this:\n"
+          "[@elysiajs/openapi] Valibot require a separate package for JSON Schema conversion"
         );
-        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;
+        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 enumToOpenApi(schema?.toJsonSchema?.());
+    return enumToOpenApi(
+      // @ts-ignore
+      schema.toJSONSchema?.() ?? schema?.toJsonSchema?.()
+    );
+  } catch (error) {
+    console.warn(error);
+  }
+};
+var enumToOpenApi = (_schema) => {
+  if (!_schema || typeof _schema !== "object") return _schema;
+  if (Kind in _schema) {
+    const schema2 = _schema;
+    if (schema2[Kind] === "Union" && schema2.anyOf && Array.isArray(schema2.anyOf) && schema2.anyOf.length > 0 && schema2.anyOf.every(
+      (item) => item && typeof item === "object" && item.const !== void 0
+    ))
+      return {
+        type: "string",
+        enum: schema2.anyOf.map((item) => item.const)
+      };
+  }
+  const schema = _schema;
+  if (schema.type === "object" && schema.properties) {
+    const properties = {};
+    for (const [key, value] of Object.entries(schema.properties))
+      properties[key] = enumToOpenApi(value);
+    return {
+      ...schema,
+      properties
+    };
   }
-  if (vendor === "arktype")
-    return schema?.toJsonSchema?.();
-  return schema.toJSONSchema?.() ?? schema?.toJsonSchema?.();
+  if (schema.type === "array" && schema.items)
+    return {
+      ...schema,
+      items: enumToOpenApi(schema.items)
+    };
+  return schema;
 };
 function toOpenAPISchema(app, exclude, references, vendors) {
   let {
@@ -233,16 +270,24 @@ function toOpenAPISchema(app, exclude, references, vendors) {
         definitions
       );
       if (params && params.type === "object" && params.properties)
-        for (const [paramName, paramSchema] of Object.entries(
-          params.properties
-        ))
+        for (const [name, schema] of Object.entries(params.properties))
           parameters.push({
-            name: paramName,
+            name,
             in: "path",
             required: true,
             // Path parameters are always required
-            schema: paramSchema
+            schema
           });
+    } else {
+      for (const match of route.path.matchAll(/:([^/]+)/g)) {
+        const name = match[1].replace("?", "");
+        parameters.push({
+          name,
+          in: "path",
+          required: true,
+          schema: { type: "string" }
+        });
+      }
     }
     if (hooks.query) {
       const query = unwrapReference(
@@ -251,32 +296,28 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       );
       if (query && query.type === "object" && query.properties) {
         const required = query.required || [];
-        for (const [queryName, querySchema] of Object.entries(
-          query.properties
-        ))
+        for (const [name, schema] of Object.entries(query.properties))
           parameters.push({
-            name: queryName,
+            name,
             in: "query",
-            required: required.includes(queryName),
-            schema: querySchema
+            required: required.includes(name),
+            schema
           });
       }
     }
     if (hooks.headers) {
       const headers = unwrapReference(
-        unwrapSchema(hooks.query, vendors),
+        unwrapSchema(hooks.headers, vendors),
         definitions
       );
       if (headers && headers.type === "object" && headers.properties) {
         const required = headers.required || [];
-        for (const [headerName, headerSchema] of Object.entries(
-          headers.properties
-        ))
+        for (const [name, schema] of Object.entries(headers.properties))
           parameters.push({
-            name: headerName,
+            name,
             in: "header",
-            required: required.includes(headerName),
-            schema: headerSchema
+            required: required.includes(name),
+            schema
           });
       }
     }
@@ -287,14 +328,12 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       );
       if (cookie && cookie.type === "object" && cookie.properties) {
         const required = cookie.required || [];
-        for (const [cookieName, cookieSchema] of Object.entries(
-          cookie.properties
-        ))
+        for (const [name, schema] of Object.entries(cookie.properties))
           parameters.push({
-            name: cookieName,
+            name,
             in: "cookie",
-            required: required.includes(cookieName),
-            schema: cookieSchema
+            required: required.includes(name),
+            schema
           });
       }
     }
@@ -342,6 +381,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
         } else {
           operation.requestBody = {
             description,
+            required: true,
             content: type === "string" || type === "number" || type === "integer" || type === "boolean" ? {
               "text/plain": {
                 schema: body
@@ -356,8 +396,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
               "multipart/form-data": {
                 schema: body
               }
-            },
-            required: true
+            }
           };
         }
       }
@@ -369,7 +408,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
         for (let [status, schema] of Object.entries(hooks.response)) {
           const response = unwrapSchema(schema, vendors);
           if (!response) continue;
-          const { type, description, $ref, ...options } = unwrapReference(response, definitions);
+          const { type, description, $ref, ..._options } = unwrapReference(response, definitions);
           operation.responses[status] = {
             description: description ?? `Response for status ${status}`,
             content: type === "void" || type === "null" || type === "undefined" ? { type, description } : type === "string" || type === "number" || type === "integer" || type === "boolean" ? {
@@ -408,7 +447,7 @@ function toOpenAPISchema(app, exclude, references, vendors) {
       }
     }
     for (let path of getPossiblePath(route.path)) {
-      const operationId = toOperationId(route.method, path);
+      const operationId = hooks.detail?.operationId ?? toOperationId(route.method, path);
       path = path.replace(/:([^/]+)/g, "{$1}");
       if (!paths[path]) paths[path] = {};
       const current = paths[path];
@@ -454,6 +493,7 @@ var withHeaders = (schema, headers) => Object.assign(schema, {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   capitalize,
+  enumToOpenApi,
   getLoosePath,
   getPossiblePath,
   toOpenAPISchema,

package/dist/cjs/scalar/index.js

@@ -143,7 +143,7 @@ var elysiaCSS = `.light-mode {
   background-image: var(--stripes), var(--rainbow);
   filter: opacity(4%) saturate(200%);
 }`;
-var ScalarRender = (info, config) => `<!doctype html>
+var ScalarRender = (info, config, embedSpec) => `<!doctype html>
 <html>
   <head>
     <title>${info.title}</title>
@@ -171,7 +171,14 @@ var ScalarRender = (info, config) => `<!doctype html>
   <body>
     <script
       id="api-reference"
-      data-url="${config.url}"
+      data-configuration='${JSON.stringify(
+  Object.assign(
+    config,
+    {
+      content: embedSpec
+    }
+  )
+)}'
     >
     </script>
     <script src="${config.cdn}" crossorigin></script>

package/dist/cjs/types.d.ts

@@ -74,6 +74,14 @@ export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extend
      * Additional reference for each endpoint
      */
     references?: AdditionalReferences;
+    /**
+     * Embed OpenAPI schema to provider body if possible
+     *
+     * This is highly discouraged, unless you really have to inline OpenAPI schema
+     *
+     * @default false
+     */
+    embedSpec?: boolean;
     /**
      * Mapping function from Standard schema to OpenAPI schema
      *

package/dist/gen/index.d.ts

@@ -1,5 +1,5 @@
-import { AdditionalReference } from '../types';
-interface OpenAPIGeneratorOptions {
+import type { AdditionalReference } from '../types';
+export interface OpenAPIGeneratorOptions {
     /**
      * Path to tsconfig.json
      * @default tsconfig.json
@@ -52,6 +52,8 @@ interface OpenAPIGeneratorOptions {
      */
     silent?: boolean;
 }
+export declare function extractRootObjects(code: string): string[];
+export declare function declarationToJSONSchema(declaration: string): AdditionalReference;
 /**
  * Auto generate OpenAPI schema from Elysia instance
  *
@@ -64,6 +66,6 @@ export declare const fromTypes: (
  * Path to file where Elysia instance is
  *
  * The path must export an Elysia instance
+ * or a literal TypeScript declaration
  */
-targetFilePath: string, { tsconfigPath, instanceName, projectRoot, overrideOutputPath, debug, compilerOptions, tmpRoot, silent }?: OpenAPIGeneratorOptions) => () => AdditionalReference | undefined;
-export {};
+targetFilePath?: string, { tsconfigPath, instanceName, projectRoot, overrideOutputPath, debug, compilerOptions, tmpRoot, silent }?: OpenAPIGeneratorOptions) => () => AdditionalReference | undefined;

package/dist/gen/index.mjs

@@ -4,16 +4,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/gen/index.ts
-import {
-  readFileSync,
-  mkdirSync,
-  writeFileSync,
-  rmSync,
-  existsSync,
-  readdirSync
-} from "fs";
-
 // node_modules/@sinclair/typebox/build/esm/value/guard/guard.mjs
 function IsObject(value) {
   return value !== null && typeof value === "object";
@@ -8298,11 +8288,9 @@ function TypeBox(...args) {
 }
 
 // src/gen/index.ts
-import { tmpdir } from "os";
-import { join } from "path";
-import { spawnSync } from "child_process";
 var matchRoute = /: Elysia<(.*)>/gs;
-var matchStatus = /(\d{3}):/g;
+var numberKey = /(\d+):/g;
+var join = (...parts) => parts.join("/").replace(/\/{1,}/g, "/");
 function extractRootObjects(code) {
   const results = [];
   let i = 0;
@@ -8334,41 +8322,89 @@ function extractRootObjects(code) {
   }
   return results;
 }
-var fromTypes = (targetFilePath, {
+function declarationToJSONSchema(declaration) {
+  const routes = {};
+  for (const route of extractRootObjects(
+    declaration.replace(numberKey, '"$1":')
+  )) {
+    let schema = TypeBox(route.replaceAll(/readonly/g, ""));
+    if (schema.type !== "object") continue;
+    const paths = [];
+    while (true) {
+      const keys = Object.keys(schema.properties);
+      if (keys.length !== 1) break;
+      paths.push(keys[0]);
+      schema = schema.properties[keys[0]];
+      if (!schema?.properties) break;
+    }
+    const method = paths.pop();
+    if (!method) continue;
+    const path = "/" + paths.join("/");
+    schema = schema.properties;
+    if (schema?.response?.type === "object") {
+      const responseSchema = {};
+      for (const key in schema.response.properties)
+        responseSchema[key] = schema.response.properties[key];
+      schema.response = responseSchema;
+    }
+    if (!routes[path]) routes[path] = {};
+    routes[path][method.toLowerCase()] = schema;
+  }
+  return routes;
+}
+var fromTypes = (targetFilePath = "src/index.ts", {
   tsconfigPath = "tsconfig.json",
   instanceName,
   projectRoot = process.cwd(),
   overrideOutputPath,
   debug = false,
   compilerOptions,
-  tmpRoot = join(tmpdir(), ".ElysiaAutoOpenAPI"),
+  tmpRoot,
   silent = false
 } = {}) => () => {
+  if (targetFilePath.trimStart().startsWith("{") && targetFilePath.trimEnd().endsWith("}"))
+    return declarationToJSONSchema(targetFilePath);
+  if (typeof process === "undefined" || typeof process.getBuiltinModule !== "function")
+    throw new Error(
+      "[@elysiajs/openapi/gen] `fromTypes` from file path is only available in Node.js/Bun environment or environments"
+    );
+  const fs = process.getBuiltinModule("fs");
+  if (!fs)
+    throw new Error(
+      "[@elysiajs/openapi/gen] `fromTypes` require `fs` module which is not available in this environment"
+    );
   try {
     if (!targetFilePath.endsWith(".ts") && !targetFilePath.endsWith(".tsx"))
       throw new Error("Only .ts files are supported");
     if (targetFilePath.startsWith("./"))
       targetFilePath = targetFilePath.slice(2);
     let src = targetFilePath.startsWith("/") ? targetFilePath : join(projectRoot, targetFilePath);
-    if (!existsSync(src))
+    if (!fs.existsSync(src))
       throw new Error(
         `Couldn't find "${targetFilePath}" from ${projectRoot}`
       );
     let targetFile;
+    if (!tmpRoot) {
+      const os = process.getBuiltinModule("os");
+      tmpRoot = join(
+        os && typeof os.tmpdir === "function" ? os.tmpdir() : projectRoot,
+        ".ElysiaAutoOpenAPI"
+      );
+    }
     if (targetFilePath.endsWith(".d.ts")) targetFile = targetFilePath;
     else {
-      if (existsSync(tmpRoot))
-        rmSync(tmpRoot, { recursive: true, force: true });
-      mkdirSync(tmpRoot, { recursive: true });
+      if (fs.existsSync(tmpRoot))
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+      fs.mkdirSync(tmpRoot, { recursive: true });
       const tsconfig = tsconfigPath.startsWith("/") ? tsconfigPath : join(projectRoot, tsconfigPath);
-      let extendsRef = existsSync(tsconfig) ? `"extends": "${join(projectRoot, "tsconfig.json")}",` : "";
+      let extendsRef = fs.existsSync(tsconfig) ? `"extends": "${join(projectRoot, "tsconfig.json")}",` : "";
       let distDir = join(tmpRoot, "dist");
       if (typeof process !== "undefined" && process.platform === "win32") {
         extendsRef = extendsRef.replace(/\\/g, "/");
         src = src.replace(/\\/g, "/");
         distDir = distDir.replace(/\\/g, "/");
       }
-      writeFileSync(
+      fs.writeFileSync(
         join(tmpRoot, "tsconfig.json"),
         `{
 	${extendsRef}
@@ -8386,6 +8422,16 @@ var fromTypes = (targetFilePath, {
 	"include": ["${src}"]
 }`
       );
+      const child_process = process.getBuiltinModule("child_process");
+      if (!child_process)
+        throw new Error(
+          "[@elysiajs/openapi/gen] `fromTypes` declaration generation require `child_process` module which is not available in this environment"
+        );
+      const { spawnSync } = child_process;
+      if (typeof spawnSync !== "function")
+        throw new Error(
+          "[@elysiajs/openapi/gen] `fromTypes` declaration generation require child_process.spawnSync which is not available in this environment"
+        );
       spawnSync(`tsc`, {
         shell: true,
         cwd: tmpRoot,
@@ -8398,7 +8444,7 @@ var fromTypes = (targetFilePath, {
         // remove leading like src or something similar
         fileName.slice(fileName.indexOf("/") + 1)
       );
-      let existed = existsSync(targetFile);
+      let existed = fs.existsSync(targetFile);
       if (!existed && !overrideOutputPath) {
         targetFile = join(
           tmpRoot,
@@ -8406,16 +8452,16 @@ var fromTypes = (targetFilePath, {
           // use original file name as-is eg. in monorepo
           fileName
         );
-        existed = existsSync(targetFile);
+        existed = fs.existsSync(targetFile);
       }
       if (!existed) {
-        rmSync(join(tmpRoot, "tsconfig.json"));
+        fs.rmSync(join(tmpRoot, "tsconfig.json"));
         console.warn(
           "[@elysiajs/openapi/gen] Failed to generate OpenAPI schema"
         );
         console.warn("Couldn't find generated declaration file");
-        if (existsSync(join(tmpRoot, "dist"))) {
-          const tempFiles = readdirSync(join(tmpRoot, "dist"), {
+        if (fs.existsSync(join(tmpRoot, "dist"))) {
+          const tempFiles = fs.readdirSync(join(tmpRoot, "dist"), {
             recursive: true
           }).filter((x) => x.toString().endsWith(".d.ts")).map((x) => `- ${x}`).join("\n");
           if (tempFiles) {
@@ -8433,9 +8479,9 @@ var fromTypes = (targetFilePath, {
         return;
       }
     }
-    const declaration = readFileSync(targetFile, "utf8");
-    if (!debug && existsSync(tmpRoot))
-      rmSync(tmpRoot, { recursive: true, force: true });
+    const declaration = fs.readFileSync(targetFile, "utf8");
+    if (!debug && fs.existsSync(tmpRoot))
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
     let instance = declaration.match(
       instanceName ? new RegExp(`${instanceName}: Elysia<(.*)`, "gs") : matchRoute
     )?.[0];
@@ -8448,34 +8494,7 @@ var fromTypes = (targetFilePath, {
           3
         )
       );
-    const routes = {};
-    for (const route of extractRootObjects(
-      instance.slice(2).replace(matchStatus, '"$1":')
-    )) {
-      let schema = TypeBox(route.replaceAll(/readonly/g, ""));
-      if (schema.type !== "object") continue;
-      const paths = [];
-      while (true) {
-        const keys = Object.keys(schema.properties);
-        if (keys.length !== 1) break;
-        paths.push(keys[0]);
-        schema = schema.properties[keys[0]];
-        if (!schema?.properties) break;
-      }
-      const method = paths.pop();
-      if (!method) continue;
-      const path = "/" + paths.join("/");
-      schema = schema.properties;
-      if (schema?.response?.type === "object") {
-        const responseSchema = {};
-        for (const key in schema.response.properties)
-          responseSchema[key] = schema.response.properties[key];
-        schema.response = responseSchema;
-      }
-      if (!routes[path]) routes[path] = {};
-      routes[path][method.toLowerCase()] = schema;
-    }
-    return routes;
+    return declarationToJSONSchema(instance.slice(2));
   } catch (error) {
     console.warn(
       "[@elysiajs/openapi/gen] Failed to generate OpenAPI schema"
@@ -8483,10 +8502,12 @@ var fromTypes = (targetFilePath, {
     console.warn(error);
     return;
   } finally {
-    if (!debug && existsSync(tmpRoot))
-      rmSync(tmpRoot, { recursive: true, force: true });
+    if (!debug && tmpRoot && fs.existsSync(tmpRoot))
+      fs.rmSync(tmpRoot, { recursive: true, force: true });
   }
 };
 export {
+  declarationToJSONSchema,
+  extractRootObjects,
   fromTypes
 };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import type { ElysiaOpenAPIConfig } from './types';
  *
  * @see https://github.com/elysiajs/elysia-swagger
  */
-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<"", {
+export declare const openapi: <const Enabled extends boolean = true, const Path extends string = "/openapi">({ enabled, path, provider, specPath, documentation, exclude, swagger, scalar, references, mapJsonSchema, embedSpec }?: ElysiaOpenAPIConfig<Enabled, Path>) => Elysia<"", {
     decorator: {};
     store: {};
     derive: {};
@@ -33,6 +33,7 @@ export declare const openapi: <const Enabled extends boolean = true, const Path
     standaloneSchema: {};
     response: {};
 }>;
+export { fromTypes } from './gen';
 export { toOpenAPISchema, withHeaders } from './openapi';
 export type { ElysiaOpenAPIConfig };
 export default openapi;