@elysiajs/openapi 1.3.2

package/dist/cjs/types.d.ts

@@ -0,0 +1,137 @@
+import type { TSchema } from 'elysia';
+import type { OpenAPIV3 } from 'openapi-types';
+import type { ApiReferenceConfiguration } from '@scalar/types';
+import type { SwaggerUIOptions } from './swagger/types';
+export type OpenAPIProvider = 'scalar' | 'swagger-ui' | null;
+type MaybeArray<T> = T | T[];
+export type AdditionalReference = {
+    [path in string]: {
+        [method in string]: {
+            params: TSchema;
+            query: TSchema;
+            headers: TSchema;
+            body: TSchema;
+            response: {
+                [status in number]: TSchema;
+            };
+        };
+    };
+};
+export type AdditionalReferences = MaybeArray<AdditionalReference | undefined | (() => AdditionalReference | undefined)>;
+export interface ElysiaOpenAPIConfig<Enabled extends boolean = true, Path extends string = '/swagger', Provider extends OpenAPIProvider = 'scalar'> {
+    /**
+     * @default true
+     */
+    enabled?: Enabled;
+    /**
+     * OpenAPI config
+     *
+     * @see https://spec.openapis.org/oas/v3.0.3.html
+     */
+    documentation?: Omit<Partial<OpenAPIV3.Document>, 'x-express-openapi-additional-middleware' | 'x-express-openapi-validation-strict'>;
+    exclude?: {
+        /**
+         * Exclude methods from OpenAPI
+         */
+        methods?: string[];
+        /**
+         * Paths to exclude from OpenAPI endpoint
+         *
+         * @default []
+         */
+        paths?: string | RegExp | (string | RegExp)[];
+        /**
+         * Determine if OpenAPI should exclude static files.
+         *
+         * @default true
+         */
+        staticFile?: boolean;
+        /**
+         * Exclude tags from OpenAPI
+         */
+        tags?: string[];
+    };
+    /**
+     * The endpoint to expose OpenAPI Documentation
+     *
+     * @default '/openapi'
+     */
+    path?: Path;
+    /**
+     * Choose your provider, Scalar or Swagger UI
+     *
+     * @default 'scalar'
+     * @see https://github.com/scalar/scalar
+     * @see https://github.com/swagger-api/swagger-ui
+     */
+    provider?: Provider;
+    /**
+     * Additional reference for each endpoint
+     */
+    references?: AdditionalReferences;
+    /**
+     * Scalar configuration to customize scalar
+     *'
+     * @see https://github.com/scalar/scalar/blob/main/documentation/configuration.md
+     */
+    scalar?: ApiReferenceConfiguration & {
+        /**
+         * Version to use for Scalar cdn bundle
+         *
+         * @default 'latest'
+         * @see https://github.com/scalar/scalar
+         */
+        version?: string;
+        /**
+         * Optional override to specifying the path for the Scalar bundle
+         *
+         * Custom URL or path to locally hosted Scalar bundle
+         *
+         * Lease blank to use default jsdeliver.net CDN
+         *
+         * @default ''
+         * @example 'https://unpkg.com/@scalar/api-reference@1.13.10/dist/browser/standalone.js'
+         * @example '/public/standalone.js'
+         * @see https://github.com/scalar/scalar
+         */
+        cdn?: string;
+    };
+    /**
+     * The endpoint to expose OpenAPI JSON specification
+     *
+     * @default '/${path}/json'
+     */
+    specPath?: string;
+    /**
+     * Options to send to SwaggerUIBundle
+     * Currently, options that are defined as functions such as requestInterceptor
+     * and onComplete are not supported.
+     */
+    swagger?: Omit<Partial<SwaggerUIOptions>, 'dom_id' | 'dom_node' | 'spec' | 'url' | 'urls' | 'layout' | 'pluginsOptions' | 'plugins' | 'presets' | 'onComplete' | 'requestInterceptor' | 'responseInterceptor' | 'modelPropertyMacro' | 'parameterMacro'> & {
+        /**
+         * Custom Swagger CSS
+         */
+        theme?: string | {
+            light: string;
+            dark: string;
+        };
+        /**
+         * Version to use for swagger cdn bundle
+         *
+         * @see unpkg.com/swagger-ui-dist
+         *
+         * @default 4.18.2
+         */
+        version?: string;
+        /**
+         * Using poor man dark mode 😭
+         */
+        autoDarkMode?: boolean;
+        /**
+         * Optional override to specifying the path for the Swagger UI bundle
+         * Custom URL or path to locally hosted Swagger UI bundle
+         */
+        cdn?: string;
+    };
+}
+export {};

package/dist/cjs/types.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/gen/index.d.ts

@@ -0,0 +1,36 @@
+import { AdditionalReference } from '../types';
+interface OpenAPIGeneratorOptions {
+    /**
+     * Path to tsconfig.json
+     * @default tsconfig.json
+     */
+    tsconfigPath?: string;
+    /**
+     * Name of the Elysia instance
+     *
+     * If multiple instances are found,
+     * instanceName should be provided
+     */
+    instanceName?: string;
+    /**
+     * Project root directory
+     *
+     * @default process.cwd()
+     */
+    projectRoot?: string;
+}
+/**
+ * Auto generate OpenAPI schema from Elysia instance
+ *
+ * It's expected that this command should run in project root
+ *
+ * @experimental use at your own risk
+ */
+export declare const fromTypes: (
+/**
+ * Path to file where Elysia instance is
+ *
+ * The path must export an Elysia instance
+ */
+targetFilePath: string, { tsconfigPath, instanceName, projectRoot }?: OpenAPIGeneratorOptions) => () => AdditionalReference | undefined;
+export {};

package/dist/gen/index.mjs

@@ -0,0 +1,108 @@
+// src/gen/index.ts
+import {
+  readFileSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  existsSync
+} from "fs";
+import { TypeBox } from "@sinclair/typemap";
+import { tmpdir } from "os";
+import { join } from "path";
+import { spawnSync } from "child_process";
+var matchRoute = /: Elysia<(.*)>/gs;
+var matchStatus = /(\d{3}):/gs;
+var wrapStatusInQuote = (value) => value.replace(matchStatus, '"$1":');
+var exec = (command, cwd) => spawnSync(command, {
+  shell: true,
+  cwd,
+  stdio: "inherit"
+});
+var fromTypes = (targetFilePath, {
+  tsconfigPath = "tsconfig.json",
+  instanceName,
+  projectRoot = process.cwd()
+} = {}) => () => {
+  if (!targetFilePath.endsWith(".ts") && !targetFilePath.endsWith(".tsx"))
+    throw new Error("Only .ts files are supported");
+  const tmpRoot = join(tmpdir(), ".ElysiaAutoOpenAPI");
+  if (existsSync(tmpRoot))
+    rmSync(tmpRoot, { recursive: true, force: true });
+  mkdirSync(tmpRoot, { recursive: true });
+  const extendsRef = existsSync(join(projectRoot, "tsconfig.json")) ? `"extends": "${join(projectRoot, "tsconfig.json")}",` : "";
+  if (!join(projectRoot, targetFilePath))
+    throw new Error("Target file does not exist");
+  writeFileSync(
+    join(tmpRoot, tsconfigPath),
+    `{
+			${extendsRef}
+			"compilerOptions": {
+				"lib": ["ESNext"],
+				"module": "ESNext",
+				"noEmit": false,
+				"moduleResolution": "bundler",
+				"skipLibCheck": true,
+				"skipDefaultLibCheck": true,
+				"emitDeclarationOnly": true,
+				"outDir": "./dist"
+			},
+			"include": ["${join(projectRoot, targetFilePath)}"]
+		}`
+  );
+  exec(`tsc`, tmpRoot);
+  try {
+    const declaration = readFileSync(
+      join(
+        tmpRoot,
+        "dist",
+        targetFilePath.replace(/.tsx$/, ".ts").replace(/.ts$/, ".d.ts")
+      ),
+      "utf8"
+    );
+    if (existsSync(tmpRoot))
+      rmSync(tmpRoot, { recursive: true, force: true });
+    let instance = declaration.match(
+      instanceName ? new RegExp(`${instanceName}: Elysia<(.*)`, "gs") : matchRoute
+    )?.[0];
+    if (!instance) return;
+    for (let i = 0; i < 3; i++)
+      instance = instance.slice(instance.indexOf("}, {", 3));
+    const routesString = wrapStatusInQuote(instance).slice(
+      3,
+      instance.indexOf("}, {", 3)
+    ) + "}\n}\n";
+    const routes = {};
+    for (let route of routesString.slice(1).split("} & {")) {
+      route = "{" + route + "}";
+      let schema = TypeBox(route);
+      if (schema.type !== "object") continue;
+      const paths = [];
+      while (true) {
+        const keys = Object.keys(schema.properties);
+        if (!keys.length || keys.length > 1) break;
+        paths.push(keys[0]);
+        schema = schema.properties[keys[0]];
+        if (!schema?.properties) break;
+      }
+      const method = paths.pop();
+      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;
+  } catch (error) {
+    console.warn("Failed to generate OpenAPI schema");
+    console.warn(error);
+    return;
+  }
+};
+export {
+  fromTypes
+};

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { Elysia } from 'elysia';
+import type { ElysiaOpenAPIConfig, OpenAPIProvider } 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 }?: ElysiaOpenAPIConfig<Enabled, Path, Provider>) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+}>;
+export { toOpenAPISchema, withHeaders } from './openapi';
+export type { ElysiaOpenAPIConfig };
+export default openapi;