@clov-std/elysia-openapi 0.0.0-stage → 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/ClovLabs/std@main/packages/elysia-openapi/logo-elysia-openapi.svg" alt="Clov Elysia OpenAPI logo" width="200" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Clov Elysia OpenAPI
+
+An OpenAPI 3.2 document and a Scalar reference for your Elysia app, built from the schemas you already wrote on your routes.
+
+The document is generated on the first request from `app.routes` and `app.models`, so routes registered after the plugin show up too. It covers `params`, `query`, `headers`, `cookie`, `body` and `response` from routes, guards and macros, and models end up in `components.schemas`.
+
+Since it targets 3.2, `QUERY` routes, nested tags (`a/b` becomes `b` under `a`) and JSON Schema 2020-12 are described as they are. The OpenAPI 3.2 types (`OpenAPIObject`, `OperationObject`, `SchemaObject`, ...) are exported as well.
+
+```bash
+bun add @clov-std/elysia-openapi elysia typebox
+```
+
+`elysia` (v2) and `typebox` are peer dependencies.
+
+## Usage
+
+```ts
+import { openapiPlugin } from '@clov-std/elysia-openapi';
+import { Elysia, t } from 'elysia';
+
+const app = new Elysia()
+	.use(openapiPlugin({ document: { info: { title: 'My API', version: '1.0.0' } } }))
+	.get(
+		'/users/:id',
+		{
+			params: t.Object({ id: t.String() }),
+			response: t.Object({ id: t.String() }),
+			detail: { tags: ['users'], summary: 'Get a user' }
+		},
+		({ params }) => ({ id: params.id })
+	)
+	.listen(3000);
+```
+
+The reference is at `http://localhost:3000/openapi`, the JSON at `http://localhost:3000/openapi/json`. Both still work under a prefix.
+
+Each operation gets an `operationId` derived from the method and path (`get` + `/users/:id` gives `getUsersById`), unique across the document.
+
+### Response headers
+
+```ts
+import { withHeaders } from '@clov-std/elysia-openapi';
+
+app.get(
+	'/users',
+	{ response: withHeaders(t.Array(t.String()), t.Object({ 'x-total-count': t.Integer() })) },
+	() => []
+);
+```
+
+This only documents the headers. Elysia doesn't validate response headers.
+
+## API
+
+### `openapiPlugin(options?)`
+
+Returns a function to pass to `app.use`.
+
+| Option     | Type                     | Default              | Description                                                                           |
+| ---------- | ------------------------ | -------------------- | ------------------------------------------------------------------------------------- |
+| `path`     | `string`                 | `'/openapi'`         | Path of the Scalar reference.                                                         |
+| `specPath` | `string`                 | `` `${path}/json` `` | Path of the JSON document.                                                            |
+| `scalar`   | `ScalarConfiguration`    | -                    | Scalar configuration, merged over the defaults.                                       |
+| `document` | `Partial<OpenAPIObject>` | -                    | Document fields to merge, generated `paths` and `components.schemas` take precedence. |
+
+### `withHeaders(schema, headers)`
+
+Returns a copy of the response `schema` documented with the `headers` object schema.
+
+## Docs
+
+API reference: [clovlabs.github.io/std](https://clovlabs.github.io/std/)
+
+## License
+
+MIT, see [LICENSE.md](LICENSE.md).

package/dist/document.d.ts

@@ -0,0 +1,11 @@
+import { type AnyElysia } from 'elysia';
+import type { OpenAPIObject } from './openapi-types-3.2';
+/**
+ * Builds the OpenAPI 3.2 document from the routes and models registered on `app`.
+ *
+ * @param app - The Elysia instance to document
+ * @param base - Document fields to merge, generated `paths` and `components.schemas` take precedence on conflicts
+ *
+ * @returns The OpenAPI document
+ */
+export declare const buildDocument: (app: AnyElysia, base?: Partial<OpenAPIObject>) => OpenAPIObject;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { openapiPlugin, type OpenAPIOptions } from './openapi';
+export { withHeaders } from './schema';
+export type { ScalarConfiguration } from './scalar-types';
+export type { SpecificationExtensions, OpenAPIObject, InfoObject, ContactObject, LicenseObject, ServerObject, ServerVariableObject, ComponentsObject, PathsObject, PathItemObject, OperationObject, ExternalDocumentationObject, ParameterLocation, ParameterStyle, ParameterObjectBase, ParameterObjectWithSchema, ParameterObjectWithContent, ParameterObject, RequestBodyObject, MediaTypeObject, EncodingObject, ResponsesObject, ResponseObject, CallbackObject, ExampleObject, LinkObject, HeaderObjectBase, HeaderObjectWithSchema, HeaderObjectWithContent, HeaderObject, TagObject, ReferenceObject, JsonSchemaType, SchemaObjectDefinition, SchemaObject, DiscriminatorObject, XMLNodeType, XMLObject, SecuritySchemeObjectBase, ApiKeySecuritySchemeObject, HttpSecuritySchemeObject, MutualTLSSecuritySchemeObject, OAuth2SecuritySchemeObject, OpenIdConnectSecuritySchemeObject, SecuritySchemeObject, OAuthFlowsObject, OAuthFlowObject, SecurityRequirementObject } from './openapi-types-3.2';

package/dist/index.js

@@ -0,0 +1,550 @@
+// @bun
+// src/openapi.ts
+import { Elysia } from "elysia";
+
+// src/document.ts
+import { StatusMapBack } from "elysia";
+import { isRecordNumber } from "elysia/utils";
+import { IsOptional, IsUnion as IsUnion2 } from "typebox";
+
+// src/schema.ts
+import { Intersect, IsIntersect, IsKind, IsObject, IsRef, IsUnion, Union } from "typebox";
+var TEXT_TYPES = new Set(["string", "number", "integer", "boolean"]);
+var componentRef = (name) => `#/components/schemas/${name.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+var uniqueSchemas = (schemas) => schemas.filter((schema, index) => schemas.findIndex((other) => Bun.deepEquals(other, schema)) === index);
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var toEnum = (schema) => {
+  const { anyOf, ...rest } = schema;
+  if (!Array.isArray(anyOf) || anyOf.length === 0 || !anyOf.every((branch) => isPlainObject(branch) && ("const" in branch) && Object.keys(branch).every((key) => key === "const" || key === "type")))
+    return schema;
+  const branches = anyOf;
+  const types = new Set(branches.map((branch) => branch.type));
+  const [type] = types;
+  return {
+    ...rest,
+    ...types.size === 1 && type !== undefined && { type },
+    enum: branches.map((branch) => branch.const)
+  };
+};
+var toSchema = (node) => {
+  if (Array.isArray(node))
+    return node.filter((item) => item?.type !== "undefined").map(toSchema);
+  if (!isPlainObject(node))
+    return node;
+  if (["File", "ArrayBuffer", "Uint8Array"].some((kind) => IsKind(node, kind)))
+    return { contentMediaType: "application/octet-stream" };
+  if (IsKind(node, "Date"))
+    return { type: "string", format: "date-time" };
+  if (IsKind(node, "FormData") || IsKind(node, "Void") || IsKind(node, "Undefined"))
+    return {};
+  if (IsKind(node, "BigInt"))
+    return { type: "integer" };
+  const schema = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (key.startsWith("~") || key === "nullable" || key === "headers" || key === "$id")
+      continue;
+    if (key === "$ref" && typeof value === "string" && !value.startsWith("#") && !value.includes(":"))
+      schema[key] = componentRef(value);
+    else if (["properties", "patternProperties", "$defs", "dependentSchemas"].includes(key) && isPlainObject(value))
+      schema[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, toSchema(sub)]));
+    else if (["const", "enum", "default", "example", "examples"].includes(key) || key.startsWith("x-"))
+      schema[key] = value;
+    else
+      schema[key] = toSchema(value);
+  }
+  if (node.nullable === true && !("anyOf" in node))
+    return { anyOf: [toEnum(schema), { type: "null" }] };
+  return toEnum(schema);
+};
+var withHeaders = (schema, headers) => Object.defineProperty(Object.create(Object.getPrototypeOf(schema), Object.getOwnPropertyDescriptors(schema)), "headers", { value: headers, enumerable: true });
+var toRootSchema = (node) => typeof node === "string" ? { $ref: componentRef(node) } : toSchema(node);
+var resolveModel = (node, models) => {
+  if (typeof node === "string")
+    return models[node];
+  if (IsRef(node))
+    return models[node.$ref];
+  return node;
+};
+var jsonTypeOf = (node) => node && ("type" in node) ? node.type : undefined;
+var descriptionOf = (node) => node && ("description" in node) && typeof node.description === "string" ? node.description : undefined;
+var hasDefault = (node) => node !== undefined && ("default" in node);
+var isText = (node, models) => {
+  const schema = resolveModel(node, models);
+  return IsUnion(schema) ? schema.anyOf.every((branch) => isText(branch, models)) : TEXT_TYPES.has(jsonTypeOf(schema));
+};
+var isPrimitive = (node, models) => {
+  const schema = resolveModel(node, models);
+  return IsUnion(schema) ? schema.anyOf.every((branch) => isPrimitive(branch, models)) : jsonTypeOf(schema) === "null" || TEXT_TYPES.has(jsonTypeOf(schema));
+};
+var isRawBinary = (node) => IsKind(node, "ArrayBuffer") || IsKind(node, "Uint8Array");
+var isFile = (node) => IsKind(node, "File");
+var containsFile = (node, models, seen = new Set) => {
+  const schema = IsRef(node) ? models[node.$ref] : node;
+  if (typeof schema !== "object" || schema === null || seen.has(schema))
+    return false;
+  seen.add(schema);
+  return isFile(schema) || Object.values(schema).some((value) => containsFile(value, models, seen));
+};
+var objectShapeOf = (node, models) => {
+  const schema = resolveModel(node, models);
+  if (IsObject(schema))
+    return {
+      properties: schema.properties,
+      required: new Set(schema.required)
+    };
+  const isUnion = IsUnion(schema);
+  const branches = isUnion ? schema.anyOf : IsIntersect(schema) ? schema.allOf : [];
+  const shapes = branches.map((branch) => objectShapeOf(branch, models)).filter((shape) => shape !== undefined);
+  if (shapes.length === 0)
+    return;
+  const required = shapes.flatMap((shape) => [...shape.required]);
+  const names = new Set(shapes.flatMap((shape) => Object.keys(shape.properties)));
+  return {
+    properties: Object.fromEntries([...names].map((name) => {
+      const schemas = uniqueSchemas(shapes.map((shape) => shape.properties[name]).filter((property) => property !== undefined));
+      if (schemas.length === 1)
+        return [name, schemas[0]];
+      return [name, isUnion ? Union(schemas) : Intersect(schemas)];
+    })),
+    required: new Set(isUnion ? required.filter((name) => shapes.every((shape) => shape.required.has(name))) : required)
+  };
+};
+
+// src/document.ts
+var FIXED_METHODS = [
+  "get",
+  "put",
+  "post",
+  "delete",
+  "options",
+  "head",
+  "patch",
+  "trace",
+  "query"
+];
+var isFixedMethod = (method) => FIXED_METHODS.includes(method);
+var FORM_MEDIA_TYPES = [
+  "application/json",
+  "application/x-www-form-urlencoded",
+  "multipart/form-data"
+];
+var isReference = (value) => ("$ref" in value);
+var toPascalCase = (value) => value.split(/[^a-zA-Z0-9]+/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+var toOperationId = (method, path) => method + (path.split("/").filter(Boolean).map((segment) => segment === "*" ? "Any" : segment.startsWith("{") ? `By${toPascalCase(segment.slice(1, -1))}` : toPascalCase(segment)).join("") || "Index");
+var toCombinedSchema = (schemas, keyword) => schemas.length === 1 ? toRootSchema(schemas[0]) : { [keyword]: schemas.map((schema) => toRootSchema(schema)) };
+var toParameters = (location, node, models) => {
+  const shape = objectShapeOf(node, models);
+  if (!shape)
+    return [];
+  return Object.entries(shape.properties).filter(([name]) => location !== "header" || !["accept", "content-type", "authorization"].includes(name.toLowerCase())).map(([name, property]) => {
+    const resolved = resolveModel(property, models);
+    const description = descriptionOf(resolved);
+    const common = {
+      name,
+      in: location,
+      ...description !== undefined && { description },
+      required: location === "path" || shape.required.has(name) && !hasDefault(resolved)
+    };
+    const schema = toRootSchema(property);
+    return location === "query" && jsonTypeOf(resolved) === "object" ? { ...common, content: { "application/json": { schema } } } : { ...common, schema };
+  });
+};
+var toBodyMediaTypes = (parse, bodies, models) => {
+  const [parser] = [parse].flat();
+  if (typeof parser === "function")
+    return ["*/*"];
+  if (typeof parser === "string") {
+    const shorthands = {
+      none: [...FORM_MEDIA_TYPES, "text/plain"],
+      text: ["text/plain"],
+      json: ["application/json"],
+      formdata: ["multipart/form-data", "application/x-www-form-urlencoded"],
+      urlencoded: ["application/x-www-form-urlencoded"],
+      arrayBuffer: ["application/octet-stream"]
+    };
+    const mediaTypes = parser.includes("/") ? [parser] : shorthands[parser];
+    if (mediaTypes)
+      return mediaTypes;
+  }
+  const schemas = bodies.map((body) => resolveModel(body, models));
+  if (schemas.some(isRawBinary))
+    return ["application/octet-stream"];
+  if (schemas.some((schema) => containsFile(schema, models)))
+    return ["multipart/form-data"];
+  if (bodies.every((body) => isPrimitive(body, models)))
+    return ["application/json", "text/plain"];
+  return FORM_MEDIA_TYPES;
+};
+var toRequestBody = (hooks, models, method) => {
+  if (["get", "head", "trace"].includes(method))
+    return;
+  const bodies = uniqueSchemas([hooks, ...hooks.schemas ?? []].map((layer) => layer.body).filter((body) => body !== undefined));
+  const [first] = bodies;
+  if (first === undefined)
+    return;
+  const schema = toCombinedSchema(bodies, "allOf");
+  const description = descriptionOf(resolveModel(first, models));
+  return {
+    ...description !== undefined && { description },
+    required: !bodies.every((body) => {
+      const resolved = resolveModel(body, models);
+      return IsOptional(body) || IsOptional(resolved) || IsUnion2(resolved) && resolved.anyOf.some((branch) => jsonTypeOf(resolveModel(branch, models)) === "undefined");
+    }),
+    content: Object.fromEntries(toBodyMediaTypes(hooks.parse, bodies, models).map((mediaType) => [
+      mediaType,
+      { schema }
+    ]))
+  };
+};
+var toResponseContent = (schemas, models) => {
+  const [first] = schemas;
+  const resolved = resolveModel(first, models);
+  const type = jsonTypeOf(resolved);
+  if (type === "void" || type === "null" || type === "undefined")
+    return;
+  if (isRawBinary(resolved) || isFile(resolved))
+    return { "application/octet-stream": { schema: toRootSchema(first) } };
+  if (schemas.length === 1 && IsUnion2(resolved)) {
+    const branches = Map.groupBy(resolved.anyOf, (branch) => {
+      const schema = resolveModel(branch, models);
+      if (isRawBinary(schema) || isFile(schema))
+        return "application/octet-stream";
+      return isText(branch, models) ? "text/plain" : "application/json";
+    });
+    if (branches.size > 1)
+      return Object.fromEntries([...branches].map(([mediaType, group]) => [
+        mediaType,
+        { schema: toCombinedSchema(group, "anyOf") }
+      ]));
+  }
+  return {
+    [isText(first, models) ? "text/plain" : "application/json"]: {
+      schema: toCombinedSchema(schemas, "anyOf")
+    }
+  };
+};
+var toResponseHeaders = (schema, models) => {
+  const resolved = resolveModel(schema, models);
+  const shape = objectShapeOf(resolved && "headers" in resolved ? resolved.headers : undefined, models);
+  if (!shape)
+    return;
+  return Object.fromEntries(Object.entries(shape.properties).map(([name, property]) => {
+    const description = descriptionOf(resolveModel(property, models));
+    return [
+      name,
+      {
+        ...description !== undefined && { description },
+        required: shape.required.has(name),
+        schema: toRootSchema(property)
+      }
+    ];
+  }));
+};
+var toResponses = (route, models) => Object.fromEntries(Object.entries(route.responses).map(([status, schemas]) => {
+  const description = descriptionOf(resolveModel(schemas[0], models)) ?? StatusMapBack[status];
+  const headers = toResponseHeaders(schemas[0], models);
+  const content = toResponseContent(schemas, models);
+  return [
+    status,
+    {
+      ...description !== undefined && { description },
+      ...headers && { headers },
+      ...content && { content }
+    }
+  ];
+}));
+var mergeParameters = (generated, overrides = []) => {
+  const parameters = new Map(generated.map((parameter) => [`${parameter.in}:${parameter.name}`, parameter]));
+  for (const parameter of overrides)
+    parameters.set(isReference(parameter) ? parameter.$ref : `${parameter.in}:${parameter.name}`, parameter);
+  return [...parameters.values()];
+};
+var mergeResponses = (generated, overrides = {}) => {
+  const responses = { ...generated };
+  for (const [status, override] of Object.entries(overrides)) {
+    const response = responses[status];
+    responses[status] = response && !isReference(response) && !isReference(override) ? { ...response, ...override } : override;
+  }
+  return responses;
+};
+var mergeRequestBody = (generated, override) => {
+  if (!override)
+    return generated;
+  if (!generated || isReference(override))
+    return override;
+  const content = { ...generated.content };
+  for (const [mediaType, media] of Object.entries(override.content ?? {})) {
+    const current = content[mediaType];
+    content[mediaType] = current && !isReference(current) && !isReference(media) ? { ...current, ...media } : media;
+  }
+  return { ...generated, ...override, content };
+};
+var toOperation = (route, models, method) => {
+  const { hooks } = route;
+  const parameters = new Map;
+  for (const layer of [hooks, ...hooks.schemas ?? []])
+    for (const [location, key] of [
+      ["path", "params"],
+      ["query", "query"],
+      ["header", "headers"],
+      ["cookie", "cookie"]
+    ])
+      for (const parameter of toParameters(location, layer[key], models))
+        parameters.set(`${location}:${parameter.name}`, parameter);
+  const {
+    hide: _hide,
+    parameters: parameterOverrides,
+    responses: responseOverrides,
+    requestBody: requestBodyOverride,
+    ...detail
+  } = hooks.detail ?? {};
+  const allParameters = mergeParameters([...parameters.values()], parameterOverrides);
+  const requestBody = mergeRequestBody(toRequestBody(hooks, models, method), requestBodyOverride);
+  const responses = mergeResponses(toResponses(route, models), responseOverrides);
+  return {
+    ...allParameters.length > 0 && { parameters: allParameters },
+    ...requestBody && { requestBody },
+    ...Object.keys(responses).length > 0 && { responses },
+    ...detail
+  };
+};
+var toTemplate = (segment) => {
+  const index = segment.indexOf(":");
+  return index === -1 ? segment : `${segment.slice(0, index)}{${segment.slice(index + 1).replace(/\?$/, "")}}`;
+};
+var toOpenAPIPaths = (path) => {
+  const segments = path.split("/");
+  const templated = segments.map(toTemplate);
+  const paths = [templated.join("/")];
+  segments.forEach((segment, index) => {
+    if (segment.includes(":") && segment.endsWith("?"))
+      paths.push(templated.slice(0, index).join("/") || "/");
+  });
+  return paths;
+};
+var isPathParameter = (parameter) => !isReference(parameter) && parameter.in === "path";
+var withPathParameters = (operation, path) => {
+  const names = path.match(/\{[^}]+\}/g)?.map((template) => template.slice(1, -1)) ?? [];
+  const parameters = (operation.parameters ?? []).filter((parameter) => !isPathParameter(parameter) || names.includes(parameter.name));
+  for (const name of names)
+    if (!parameters.some((parameter) => isPathParameter(parameter) && parameter.name === name))
+      parameters.push({ name, in: "path", required: true, schema: { type: "string" } });
+  const { parameters: _parameters, ...rest } = operation;
+  return parameters.length > 0 ? { ...rest, parameters } : rest;
+};
+var toTags = (names, base) => {
+  const tags = new Map;
+  for (const name of names) {
+    const segments = name.split("/").filter(Boolean);
+    segments.forEach((segment, index) => {
+      const tagName = index === segments.length - 1 ? name : segments.slice(0, index + 1).join("/");
+      if (!tags.has(tagName))
+        tags.set(tagName, {
+          name: tagName,
+          ...index > 0 && {
+            summary: segment,
+            parent: segments.slice(0, index).join("/")
+          }
+        });
+    });
+  }
+  for (const tag of base)
+    tags.set(tag.name, { ...tags.get(tag.name), ...tag });
+  return [...tags.values()];
+};
+var toStatusMap = (response) => {
+  if (response === undefined)
+    return {};
+  return typeof response === "object" && isRecordNumber(response) ? response : { 200: response };
+};
+var toResponseLayers = (hooks, ownResponse) => {
+  const own = toStatusMap(ownResponse);
+  const merged = (hooks.schemas ?? []).map((layer) => toStatusMap(layer.response));
+  return Object.fromEntries(Object.entries(toStatusMap(hooks.response)).map(([status, schema]) => {
+    const layers = uniqueSchemas([own[status], ...merged.map((layer) => layer[status])].filter((layer) => layer !== undefined));
+    return [status, layers.length > 0 ? layers : [schema]];
+  }));
+};
+var readRoutes = (app) => {
+  const internals = new Map(app["~routes"].map(([method, path, , owner, hook]) => [
+    `${method} ${path}`,
+    {
+      config: owner["~config"],
+      ownResponse: hook?.response
+    }
+  ]));
+  return app.routes.map(({ method, path, hooks }) => {
+    const routeHooks = hooks ?? {};
+    const { config, ownResponse } = internals.get(`${method} ${path}`) ?? {};
+    const { operationId: _operationId, ...instanceDetail } = config?.detail ?? {};
+    const tags = [
+      ...new Set([
+        ...config?.tags ?? [],
+        ...instanceDetail.tags ?? [],
+        ...routeHooks.detail?.tags ?? []
+      ])
+    ].filter(Boolean);
+    return {
+      method,
+      path,
+      hooks: {
+        ...routeHooks,
+        detail: {
+          ...instanceDetail,
+          ...routeHooks.detail,
+          ...tags.length > 0 && { tags }
+        }
+      },
+      responses: toResponseLayers(routeHooks, ownResponse),
+      bare: hooks === undefined
+    };
+  });
+};
+var buildDocument = (app, base = {}) => {
+  const models = app.models;
+  const paths = {};
+  const tagNames = new Set;
+  const generated = new Map;
+  for (const route of readRoutes(app)) {
+    const routeMethod = route.method.toLowerCase();
+    if (route.hooks.detail?.hide || routeMethod === "ws")
+      continue;
+    if (routeMethod === "options" && route.bare && /^\/(\*)?$|\/\*$/.test(route.path))
+      continue;
+    for (const tag of route.hooks.detail?.tags ?? [])
+      tagNames.add(tag);
+    const isCatchAll = routeMethod === "*";
+    for (const method of isCatchAll ? FIXED_METHODS : [routeMethod]) {
+      const operation = toOperation(route, models, method);
+      for (const path of toOpenAPIPaths(route.path)) {
+        const item = { ...paths[path] };
+        if (isCatchAll && isFixedMethod(method) && item[method])
+          continue;
+        const identified = withPathParameters(operation, path);
+        generated.set(identified, identified.operationId ?? toOperationId(method, path));
+        if (isFixedMethod(method))
+          item[method] = identified;
+        else
+          item.additionalOperations = {
+            ...item.additionalOperations,
+            [route.method]: identified
+          };
+        paths[path] = item;
+      }
+    }
+  }
+  const mergedPaths = {
+    ...base.paths,
+    ...Object.fromEntries(Object.entries(paths).map(([path, item]) => [
+      path,
+      { ...base.paths?.[path], ...item }
+    ]))
+  };
+  const operations = Object.values(mergedPaths).flatMap((item) => [
+    ...FIXED_METHODS.map((method) => item?.[method]),
+    ...Object.values(item?.additionalOperations ?? {})
+  ]);
+  const operationIds = new Set(operations.filter((operation) => operation !== undefined && !generated.has(operation)).map((operation) => operation?.operationId));
+  for (const [operation, operationId] of generated) {
+    if (!operations.includes(operation))
+      continue;
+    let candidate = operationId;
+    for (let suffix = 2;operationIds.has(candidate); suffix++)
+      candidate = `${operationId}${suffix}`;
+    operationIds.add(candidate);
+    operation.operationId = candidate;
+  }
+  return {
+    openapi: "3.2.1",
+    ...base,
+    info: {
+      title: "Elysia Documentation",
+      description: "API documentation for Elysia",
+      version: "1.0.0",
+      ...base.info
+    },
+    paths: mergedPaths,
+    tags: toTags(tagNames, base.tags ?? []),
+    components: {
+      ...base.components,
+      schemas: {
+        ...base.components?.schemas,
+        ...Object.fromEntries(Object.entries(models).map(([name, model]) => [
+          name,
+          toSchema(model)
+        ]))
+      }
+    }
+  };
+};
+
+// src/openapi.ts
+var renderScalar = (title, configuration) => `<!doctype html>
+<html>
+	<head>
+		<title>${Bun.escapeHTML(title)}</title>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+	</head>
+	<body>
+		<div id="app"></div>
+		<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+		<script>
+			Scalar.createApiReference('#app', ${JSON.stringify(configuration).replaceAll("<", "\\u003c")});
+		</script>
+	</body>
+</html>`;
+var openapiPlugin = ({
+  path = "/openapi",
+  specPath = `${path}/json`,
+  scalar,
+  document: base
+} = {}) => {
+  const scalarOptions = {
+    defaultOpenAllTags: false,
+    defaultOpenFirstTag: false,
+    documentDownloadType: "both",
+    expandAllModelSections: false,
+    expandAllResponses: false,
+    expandAllSchemaProperties: false,
+    hideClientButton: true,
+    hideDarkModeToggle: false,
+    hideModels: false,
+    hideSearch: false,
+    hideTestRequestButton: false,
+    isEditable: false,
+    layout: "modern",
+    operationTitleSource: "summary",
+    orderRequiredPropertiesFirst: true,
+    orderSchemaPropertiesBy: "preserve",
+    persistAuth: true,
+    showDeveloperTools: "localhost",
+    showOperationId: true,
+    showSidebar: true,
+    telemetry: false,
+    withDefaultFonts: true,
+    expandAllParameters: true,
+    theme: "elysiajs",
+    mcp: {
+      disabled: true
+    },
+    agent: {
+      disabled: true
+    },
+    darkMode: true,
+    ...scalar
+  };
+  return (host) => {
+    let document;
+    const getDocument = () => document ??= buildDocument(host, base);
+    host.use(new Elysia({ name: "openapiPlugin" }).guard({ detail: { hide: true } }, (plugin) => plugin.get(path, ({ path: requestPath }) => new Response(renderScalar(getDocument().info.title, {
+      ...scalarOptions,
+      url: requestPath.replace(/\/$/, "").slice(0, -path.length) + specPath
+    }), { headers: { "content-type": "text/html; charset=utf-8" } })).get(specPath, getDocument)));
+    return host;
+  };
+};
+export {
+  openapiPlugin,
+  withHeaders
+};