npm - @elysiajs/openapi - Versions diffs - 1.3.2 - Mend

@elysiajs/openapi 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/LICENSE +7 -0
package/README.md +101 -0
package/bun.lock +537 -0
package/bunfig.toml +2 -0
package/dist/cjs/gen/index.js +127 -0
package/dist/cjs/index.d.ts +35 -0
package/dist/cjs/index.js +639 -0
package/dist/cjs/openapi.d.ts +25 -0
package/dist/cjs/openapi.js +285 -0
package/dist/cjs/scalar/index.js +183 -0
package/dist/cjs/swagger/index.js +129 -0
package/dist/cjs/swagger/types.js +18 -0
package/dist/cjs/types.d.ts +137 -0
package/dist/cjs/types.js +18 -0
package/dist/gen/index.d.ts +36 -0
package/dist/gen/index.mjs +108 -0
package/dist/index.d.ts +35 -0
package/dist/index.mjs +612 -0
package/dist/openapi.d.ts +25 -0
package/dist/openapi.mjs +257 -0
package/dist/scalar/index.d.ts +3 -0
package/dist/scalar/index.mjs +158 -0
package/dist/swagger/index.d.ts +7 -0
package/dist/swagger/index.mjs +103 -0
package/dist/swagger/types.d.ts +274 -0
package/dist/swagger/types.mjs +0 -0
package/dist/types.d.ts +137 -0
package/dist/types.mjs +0 -0
package/package.json +92 -0

package/dist/index.mjs ADDED Viewed

@@ -0,0 +1,612 @@
+// src/index.ts
+import { Elysia } from "elysia";
+// src/swagger/index.ts
+function isSchemaObject(schema) {
+  return "type" in schema || "properties" in schema || "items" in schema;
+}
+function isDateTimeProperty(key, schema) {
+  return (key === "createdAt" || key === "updatedAt") && "anyOf" in schema && Array.isArray(schema.anyOf);
+}
+function transformDateProperties(schema) {
+  if (!isSchemaObject(schema) || typeof schema !== "object" || schema === null)
+    return schema;
+  const newSchema = { ...schema };
+  Object.entries(newSchema).forEach(([key, value]) => {
+    if (isSchemaObject(value)) {
+      if (isDateTimeProperty(key, value)) {
+        const dateTimeFormat = value.anyOf?.find(
+          (item) => isSchemaObject(item) && item.format === "date-time"
+        );
+        if (dateTimeFormat) {
+          const dateTimeSchema = {
+            type: "string",
+            format: "date-time",
+            default: dateTimeFormat.default
+          };
+          newSchema[key] = dateTimeSchema;
+        }
+      } else {
+        ;
+        newSchema[key] = transformDateProperties(value);
+      }
+    }
+  });
+  return newSchema;
+}
+var SwaggerUIRender = (info, config) => {
+  const {
+    version = "latest",
+    theme = `https://unpkg.com/swagger-ui-dist@${version ?? "latest"}/swagger-ui.css`,
+    cdn = `https://unpkg.com/swagger-ui-dist@${version}/swagger-ui-bundle.js`,
+    autoDarkMode = true,
+    ...rest
+  } = config;
+  const stringifiedOptions = JSON.stringify(
+    {
+      dom_id: "#swagger-ui",
+      ...rest
+    },
+    (_, value) => typeof value === "function" ? void 0 : value
+  );
+  const options = JSON.parse(stringifiedOptions);
+  if (options.components && options.components.schemas)
+    options.components.schemas = Object.fromEntries(
+      Object.entries(options.components.schemas).map(([key, schema]) => [
+        key,
+        transformDateProperties(schema)
+      ])
+    );
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${info.title}</title>
+    <meta
+        name="description"
+        content="${info.description}"
+    />
+    <meta
+        name="og:description"
+        content="${info.description}"
+    />
+    ${autoDarkMode && typeof theme === "string" ? `<style>
+@media (prefers-color-scheme: dark) {
+    body {
+        background-color: #222;
+        color: #faf9a;
+    }
+    .swagger-ui {
+        filter: invert(92%) hue-rotate(180deg);
+    }
+    .swagger-ui .microlight {
+        filter: invert(100%) hue-rotate(180deg);
+    }
+}
+</style>` : ""}
+    ${typeof theme === "string" ? `<link rel="stylesheet" href="${theme}" />` : `<link rel="stylesheet" media="(prefers-color-scheme: light)" href="${theme.light}" />
+<link rel="stylesheet" media="(prefers-color-scheme: dark)" href="${theme.dark}" />`}
+</head>
+<body>
+    <div id="swagger-ui"></div>
+    <script src="${cdn}" crossorigin></script>
+    <script>
+        window.onload = () => {
+            window.ui = SwaggerUIBundle(${stringifiedOptions});
+        };
+    </script>
+</body>
+</html>`;
+};
+// src/scalar/index.ts
+var elysiaCSS = `.light-mode {
+  --scalar-color-1: #2a2f45;
+  --scalar-color-2: #757575;
+  --scalar-color-3: #8e8e8e;
+  --scalar-color-accent: #f06292;
+  --scalar-background-1: #fff;
+  --scalar-background-2: #f6f6f6;
+  --scalar-background-3: #e7e7e7;
+  --scalar-border-color: rgba(0, 0, 0, 0.1);
+}
+.dark-mode {
+  --scalar-color-1: rgba(255, 255, 255, 0.9);
+  --scalar-color-2: rgba(156, 163, 175, 1);
+  --scalar-color-3: rgba(255, 255, 255, 0.44);
+  --scalar-color-accent: #f06292;
+  --scalar-background-1: #111728;
+  --scalar-background-2: #1e293b;
+  --scalar-background-3: #334155;
+  --scalar-background-accent: #f062921f;
+  --scalar-border-color: rgba(255, 255, 255, 0.1);
+}
+/* Document Sidebar */
+.light-mode .t-doc__sidebar,
+.dark-mode .t-doc__sidebar {
+  --scalar-sidebar-background-1: var(--scalar-background-1);
+  --scalar-sidebar-color-1: var(--scalar-color-1);
+  --scalar-sidebar-color-2: var(--scalar-color-2);
+  --scalar-sidebar-border-color: var(--scalar-border-color);
+  --scalar-sidebar-item-hover-background: var(--scalar-background-2);
+  --scalar-sidebar-item-hover-color: currentColor;
+  --scalar-sidebar-item-active-background: #f062921f;
+  --scalar-sidebar-color-active: var(--scalar-color-accent);
+  --scalar-sidebar-search-background: transparent;
+  --scalar-sidebar-search-color: var(--scalar-color-3);
+  --scalar-sidebar-search-border-color: var(--scalar-border-color);
+}
+/* advanced */
+.light-mode {
+  --scalar-button-1: rgb(49 53 56);
+  --scalar-button-1-color: #fff;
+  --scalar-button-1-hover: rgb(28 31 33);
+  --scalar-color-green: #069061;
+  --scalar-color-red: #ef0006;
+  --scalar-color-yellow: #edbe20;
+  --scalar-color-blue: #0082d0;
+  --scalar-color-orange: #fb892c;
+  --scalar-color-purple: #5203d1;
+  --scalar-scrollbar-color: rgba(0, 0, 0, 0.18);
+  --scalar-scrollbar-color-active: rgba(0, 0, 0, 0.36);
+}
+.dark-mode {
+  --scalar-button-1: #f6f6f6;
+  --scalar-button-1-color: #000;
+  --scalar-button-1-hover: #e7e7e7;
+  --scalar-color-green: #a3ffa9;
+  --scalar-color-red: #ffa3a3;
+  --scalar-color-yellow: #fffca3;
+  --scalar-color-blue: #a5d6ff;
+  --scalar-color-orange: #e2ae83;
+  --scalar-color-purple: #d2a8ff;
+  --scalar-scrollbar-color: rgba(255, 255, 255, 0.24);
+  --scalar-scrollbar-color-active: rgba(255, 255, 255, 0.48);
+}
+.section-flare {
+  width: 100%;
+  height: 400px;
+  position: absolute;
+}
+.section-flare-item:first-of-type:before {
+  content: "";
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  --stripes: repeating-linear-gradient(100deg, #fff 0%, #fff 0%, transparent 2%, transparent 12%, #fff 17%);
+  --stripesDark: repeating-linear-gradient(100deg, #000 0%, #000 0%, transparent 10%, transparent 12%, #000 17%);
+  --rainbow: repeating-linear-gradient(100deg, #60a5fa 10%, #e879f9 16%, #5eead4 22%, #60a5fa 30%);
+  contain: strict;
+  contain-intrinsic-size: 100vw 40vh;
+  background-image: var(--stripesDark), var(--rainbow);
+  background-size: 300%, 200%;
+  background-position: 50% 50%, 50% 50%;
+  filter: opacity(20%) saturate(200%);
+  -webkit-mask-image: radial-gradient(ellipse at 100% 0%, black 40%, transparent 70%);
+  mask-image: radial-gradient(ellipse at 100% 0%, black 40%, transparent 70%);
+  pointer-events: none;
+}
+.section-flare-item:first-of-type:after {
+  content: "";
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  background-image: var(--stripes), var(--rainbow);
+  background-size: 200%, 100%;
+  background-attachment: fixed;
+  mix-blend-mode: difference;
+  background-image: var(--stripesDark), var(--rainbow);
+  pointer-events: none;
+}
+.light-mode .section-flare-item:first-of-type:after,
+.light-mode .section-flare-item:first-of-type:before {
+  background-image: var(--stripes), var(--rainbow);
+  filter: opacity(4%) saturate(200%);
+}`;
+var ScalarRender = (info, config) => `<!doctype html>
+<html>
+  <head>
+    <title>${info.title}</title>
+    <meta
+        name="description"
+        content="${info.description}"
+    />
+    <meta
+        name="og:description"
+        content="${info.description}"
+    />
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+    <style>
+      body {
+        margin: 0;
+      }
+    </style>
+    <style>
+      ${config.customCss ?? elysiaCSS}
+    </style>
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      data-url="${config.url}"
+    >
+    </script>
+    <script src="${config.cdn}" crossorigin></script>
+  </body>
+</html>`;
+// src/openapi.ts
+import { t } from "elysia";
+var capitalize = (word) => word.charAt(0).toUpperCase() + word.slice(1);
+var toRef = (name) => t.Ref(`#/components/schemas/${name}`);
+var toOperationId = (method, paths) => {
+  let operationId = method.toLowerCase();
+  if (!paths || paths === "/") return operationId + "Index";
+  for (const path of paths.split("/"))
+    operationId += path.includes(":") ? "By" + capitalize(path.replace(":", "")) : capitalize(path);
+  operationId = operationId.replace(/\?/g, "Optional");
+  return operationId;
+};
+var optionalParamsRegex = /(\/:\w+\?)/g;
+var getPossiblePath = (path) => {
+  const optionalParams = path.match(optionalParamsRegex);
+  if (!optionalParams) return [path];
+  const originalPath = path.replace(/\?/g, "");
+  const paths = [originalPath];
+  for (let i = 0; i < optionalParams.length; i++) {
+    const newPath = path.replace(optionalParams[i], "");
+    paths.push(...getPossiblePath(newPath));
+  }
+  return paths;
+};
+function toOpenAPISchema(app, exclude, references) {
+  const {
+    methods: excludeMethods = ["OPTIONS"],
+    staticFile: excludeStaticFile = true,
+    tags: excludeTags
+  } = exclude ?? {};
+  const excludePaths = Array.isArray(exclude?.paths) ? exclude.paths : typeof exclude?.paths !== "undefined" ? [exclude.paths] : [];
+  const paths = /* @__PURE__ */ Object.create(null);
+  const routes = app.getGlobalRoutes();
+  if (references) {
+    if (!Array.isArray(references)) references = [references];
+    for (let i = 0; i < references.length; i++) {
+      const reference = references[i];
+      if (typeof reference === "function") references[i] = reference();
+    }
+  }
+  for (const route of routes) {
+    if (route.hooks?.detail?.hide) continue;
+    const method = route.method.toLowerCase();
+    if (excludeStaticFile && route.path.includes(".") || excludePaths.includes(route.path) || excludeMethods.includes(method))
+      continue;
+    const hooks = route.hooks ?? {};
+    if (references)
+      for (const reference of references) {
+        const refer = reference[route.path]?.[method];
+        if (!refer) continue;
+        if (!hooks.body && refer.body) hooks.body = refer.body;
+        if (!hooks.query && refer.query) hooks.query = refer.query;
+        if (!hooks.params && refer.params) hooks.params = refer.params;
+        if (!hooks.headers && refer.headers)
+          hooks.headers = refer.headers;
+        if (!hooks.response && refer.response) {
+          hooks.response = {};
+          for (const [status, schema] of Object.entries(
+            refer.response
+          ))
+            if (!hooks.response[status])
+              hooks.response[status] = schema;
+        }
+      }
+    if (excludeTags && hooks.detail.tags?.some((tag) => excludeTags?.includes(tag)))
+      continue;
+    const operation = {
+      ...hooks.detail
+    };
+    const parameters = [];
+    if (hooks.params) {
+      if (typeof hooks.params === "string")
+        hooks.params = toRef(hooks.params);
+      if (hooks.params.type === "object" && hooks.params.properties) {
+        for (const [paramName, paramSchema] of Object.entries(
+          hooks.params.properties
+        ))
+          parameters.push({
+            name: paramName,
+            in: "path",
+            required: true,
+            // Path parameters are always required
+            schema: paramSchema
+          });
+      }
+    }
+    if (hooks.query) {
+      if (typeof hooks.query === "string")
+        hooks.query = toRef(hooks.query);
+      if (hooks.query.type === "object" && hooks.query.properties) {
+        const required = hooks.query.required || [];
+        for (const [queryName, querySchema] of Object.entries(
+          hooks.query.properties
+        ))
+          parameters.push({
+            name: queryName,
+            in: "query",
+            required: required.includes(queryName),
+            schema: querySchema
+          });
+      }
+    }
+    if (hooks.headers) {
+      if (typeof hooks.headers === "string")
+        hooks.headers = toRef(hooks.headers);
+      if (hooks.headers.type === "object" && hooks.headers.properties) {
+        const required = hooks.headers.required || [];
+        for (const [headerName, headerSchema] of Object.entries(
+          hooks.headers.properties
+        ))
+          parameters.push({
+            name: headerName,
+            in: "header",
+            required: required.includes(headerName),
+            schema: headerSchema
+          });
+      }
+    }
+    if (hooks.cookie) {
+      if (typeof hooks.cookie === "string")
+        hooks.cookie = toRef(hooks.cookie);
+      if (hooks.cookie.type === "object" && hooks.cookie.properties) {
+        const required = hooks.cookie.required || [];
+        for (const [cookieName, cookieSchema] of Object.entries(
+          hooks.cookie.properties
+        ))
+          parameters.push({
+            name: cookieName,
+            in: "cookie",
+            required: required.includes(cookieName),
+            schema: cookieSchema
+          });
+      }
+    }
+    if (parameters.length > 0) operation.parameters = parameters;
+    if (hooks.body) {
+      if (typeof hooks.body === "string") hooks.body = toRef(hooks.body);
+      if (hooks.parse) {
+        const content = {};
+        const parsers = hooks.parse;
+        for (const parser of parsers) {
+          if (typeof parser.fn === "function") continue;
+          switch (parser.fn) {
+            case "text":
+            case "text/plain":
+              content["text/plain"] = { schema: hooks.body };
+              continue;
+            case "urlencoded":
+            case "application/x-www-form-urlencoded":
+              content["application/x-www-form-urlencoded"] = {
+                schema: hooks.body
+              };
+              continue;
+            case "json":
+            case "application/json":
+              content["application/json"] = { schema: hooks.body };
+              continue;
+            case "formdata":
+            case "multipart/form-data":
+              content["multipart/form-data"] = {
+                schema: hooks.body
+              };
+              continue;
+          }
+        }
+        operation.requestBody = { content, required: true };
+      } else {
+        operation.requestBody = {
+          content: {
+            "application/json": {
+              schema: hooks.body
+            },
+            "application/x-www-form-urlencoded": {
+              schema: hooks.body
+            },
+            "multipart/form-data": {
+              schema: hooks.body
+            }
+          },
+          required: true
+        };
+      }
+    }
+    if (hooks.response) {
+      operation.responses = {};
+      if (typeof hooks.response === "object" && !hooks.response.type && !hooks.response.$ref) {
+        for (let [status, schema] of Object.entries(hooks.response)) {
+          if (typeof schema === "string") schema = toRef(schema);
+          const { type, examples, $ref, ...options } = schema;
+          operation.responses[status] = {
+            description: `Response for status ${status}`,
+            ...options,
+            content: type === "void" || type === "null" || type === "undefined" ? schema : {
+              "application/json": {
+                schema
+              }
+            }
+          };
+        }
+      } else {
+        if (typeof hooks.response === "string")
+          hooks.response = toRef(hooks.response);
+        operation.responses["200"] = {
+          description: "Successful response",
+          content: {
+            "application/json": {
+              schema: hooks.response
+            }
+          }
+        };
+      }
+    }
+    for (let path of getPossiblePath(route.path)) {
+      const operationId = toOperationId(route.method, path);
+      path = path.replace(/:([^/]+)/g, "{$1}");
+      if (!paths[path]) paths[path] = {};
+      const current = paths[path];
+      if (method !== "all") {
+        current[method] = {
+          ...operation,
+          operationId
+        };
+        continue;
+      }
+      for (const method2 of [
+        "get",
+        "post",
+        "put",
+        "delete",
+        "patch",
+        "head",
+        "options",
+        "trace"
+      ])
+        current[method2] = {
+          ...operation,
+          operationId
+        };
+    }
+  }
+  const schemas = app.getGlobalDefinitions?.().type;
+  return {
+    components: {
+      schemas
+    },
+    paths
+  };
+}
+var withHeaders = (schema, headers) => Object.assign(schema, {
+  headers
+});
+// src/index.ts
+var openapi = ({
+  enabled = true,
+  path = "/openapi",
+  provider = "scalar",
+  specPath = `${path}/json`,
+  documentation = {},
+  exclude,
+  swagger,
+  scalar,
+  references
+} = {}) => {
+  if (!enabled) return new Elysia({ name: "@elysiajs/openapi" });
+  const info = {
+    title: "Elysia Documentation",
+    description: "Development documentation",
+    version: "0.0.0",
+    ...documentation.info
+  };
+  const relativePath = specPath.startsWith("/") ? specPath.slice(1) : specPath;
+  let totalRoutes = 0;
+  let cachedSchema;
+  const app = new Elysia({ name: "@elysiajs/openapi" }).use((app2) => {
+    if (provider === null) return app2;
+    return app2.get(
+      path,
+      new Response(
+        provider === "swagger-ui" ? SwaggerUIRender(info, {
+          url: relativePath,
+          dom_id: "#swagger-ui",
+          version: "latest",
+          autoDarkMode: true,
+          ...swagger
+        }) : ScalarRender(info, {
+          url: relativePath,
+          version: "latest",
+          cdn: `https://cdn.jsdelivr.net/npm/@scalar/api-reference@${scalar?.version ?? "latest"}/dist/browser/standalone.min.js`,
+          ...scalar,
+          _integration: "elysiajs"
+        }),
+        {
+          headers: {
+            "content-type": "text/html; charset=utf8"
+          }
+        }
+      ),
+      {
+        detail: {
+          hide: true
+        }
+      }
+    );
+  }).get(
+    specPath,
+    function openAPISchema() {
+      if (totalRoutes === app.routes.length) return cachedSchema;
+      totalRoutes = app.routes.length;
+      const {
+        paths,
+        components: { schemas }
+      } = toOpenAPISchema(app, exclude, references);
+      return cachedSchema = {
+        openapi: "3.0.3",
+        ...documentation,
+        tags: !exclude?.tags ? documentation.tags : documentation.tags?.filter(
+          (tag) => !exclude.tags?.includes(tag.name)
+        ),
+        info: {
+          title: "Elysia Documentation",
+          description: "Development documentation",
+          version: "0.0.0",
+          ...documentation.info
+        },
+        paths: {
+          ...paths,
+          ...documentation.paths
+        },
+        components: {
+          ...documentation.components,
+          schemas: {
+            ...schemas,
+            ...documentation.components?.schemas
+          }
+        }
+      };
+    },
+    {
+      detail: {
+        hide: true
+      }
+    }
+  );
+  return app;
+};
+var index_default = openapi;
+export {
+  index_default as default,
+  openapi,
+  toOpenAPISchema,
+  withHeaders
+};

package/dist/openapi.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import { type AnyElysia, type TSchema } from 'elysia';
+import type { OpenAPIV3 } from 'openapi-types';
+import type { TProperties } from '@sinclair/typebox';
+import type { AdditionalReferences, ElysiaOpenAPIConfig } from './types';
+export declare const capitalize: (word: string) => string;
+/**
+ * Get all possible paths of a path with optional parameters
+ * @param {string} path
+ * @returns {string[]} paths
+ */
+export declare const getPossiblePath: (path: string) => string[];
+/**
+ * Converts Elysia routes to OpenAPI 3.0.3 paths schema
+ * @param routes Array of Elysia route objects
+ * @returns OpenAPI paths object
+ */
+export declare function toOpenAPISchema(app: AnyElysia, exclude?: ElysiaOpenAPIConfig['exclude'], references?: AdditionalReferences): {
+    components: {
+        schemas: Record<string, TSchema>;
+    };
+    paths: OpenAPIV3.PathsObject<{}, {}>;
+};
+export declare const withHeaders: (schema: TSchema, headers: TProperties) => TSchema & {
+    headers: TProperties;
+};