@hectoday/openapi 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -24,14 +24,70 @@ interface OpenApiConfig {
   security?: Array<Record<string, string[]>>;
   securitySchemes?: Record<string, SecurityScheme>;
 }
-interface SecurityScheme {
-  type: "http" | "apiKey" | "oauth2" | "openIdConnect";
-  scheme?: string;
+type OAuth2Scopes = Record<string, string>;
+type OAuth2ImplicitFlow = {
+  authorizationUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+type OAuth2PasswordFlow = {
+  tokenUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+type OAuth2ClientCredentialsFlow = {
+  tokenUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+type OAuth2AuthorizationCodeFlow = {
+  authorizationUrl: string;
+  tokenUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+type OAuth2FlowMap = {
+  implicit: OAuth2ImplicitFlow;
+  password: OAuth2PasswordFlow;
+  clientCredentials: OAuth2ClientCredentialsFlow;
+  authorizationCode: OAuth2AuthorizationCodeFlow;
+};
+type OAuth2Flows = {
+  implicit: OAuth2FlowMap["implicit"];
+} | {
+  password: OAuth2FlowMap["password"];
+} | {
+  clientCredentials: OAuth2FlowMap["clientCredentials"];
+} | {
+  authorizationCode: OAuth2FlowMap["authorizationCode"];
+} | ({
+  implicit: OAuth2FlowMap["implicit"];
+} & Partial<Omit<OAuth2FlowMap, "implicit">>) | ({
+  password: OAuth2FlowMap["password"];
+} & Partial<Omit<OAuth2FlowMap, "password">>) | ({
+  clientCredentials: OAuth2FlowMap["clientCredentials"];
+} & Partial<Omit<OAuth2FlowMap, "clientCredentials">>) | ({
+  authorizationCode: OAuth2FlowMap["authorizationCode"];
+} & Partial<Omit<OAuth2FlowMap, "authorizationCode">>);
+type SecurityScheme = {
+  type: "http";
+  scheme: string;
   bearerFormat?: string;
-  name?: string;
-  in?: "query" | "header" | "cookie";
   description?: string;
-}
+} | {
+  type: "apiKey";
+  name: string;
+  in: "query" | "header" | "cookie";
+  description?: string;
+} | {
+  type: "oauth2";
+  flows: OAuth2Flows;
+  description?: string;
+} | {
+  type: "openIdConnect";
+  openIdConnectUrl: string;
+  description?: string;
+};
 interface OpenApiResult {
   /** Creates a GET route that serves the OpenAPI JSON document. */
   spec: (route: {
@@ -44,4 +100,4 @@ interface OpenApiResult {
 }
 declare function openapi(routes: RouteDescriptor[], config: OpenApiConfig): OpenApiResult;
 //#endregion
-export { OpenApiConfig, OpenApiResult, SecurityScheme, openapi };
+export { OAuth2AuthorizationCodeFlow, OAuth2ClientCredentialsFlow, OAuth2Flows, OAuth2ImplicitFlow, OAuth2PasswordFlow, OAuth2Scopes, OpenApiConfig, OpenApiResult, SecurityScheme, openapi };

package/dist/index.mjs

@@ -1,10 +1,28 @@
-import { z } from "zod";
-import { createDocument, extendZodWithOpenApi } from "zod-openapi";
+import * as z from "zod/v4";
+import { createDocument } from "zod-openapi";
 //#region src/index.ts
-let extended = false;
+function extractPathParamNames(path) {
+	return Array.from(path.matchAll(/:(\w+)/g), (match) => match[1]);
+}
 function toOpenApiPath(path) {
 	return path.replace(/:(\w+)/g, "{$1}");
 }
+function getSchemaObjectKeys(schema) {
+	return Object.keys(schema.shape);
+}
+function assertPathParamsMatchPath(method, path, schema) {
+	const pathParamNames = extractPathParamNames(path);
+	const schemaParamNames = getSchemaObjectKeys(schema);
+	if (pathParamNames.length === schemaParamNames.length && pathParamNames.every((name) => schemaParamNames.includes(name))) return;
+	if (pathParamNames.length === 0) throw new Error(`params schema for ${method} ${path} cannot define path params when the path has none`);
+	throw new Error(`params schema for ${method} ${path} must define exactly these path params: ${pathParamNames.join(", ")}`);
+}
+function responseCanHaveBody(status) {
+	return !(status >= 100 && status < 200) && status !== 204 && status !== 205 && status !== 304;
+}
+function operationCanHaveResponseBody(method, status) {
+	return method.toUpperCase() !== "HEAD" && responseCanHaveBody(status);
+}
 const STATUS_TEXT = {
 	100: "Continue",
 	101: "Switching Protocols",
@@ -68,6 +86,9 @@ const STATUS_TEXT = {
 	510: "Not Extended",
 	511: "Network Authentication Required"
 };
+function escapeHtmlAttr(s) {
+	return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
 function scalarHtml(specUrl) {
 	return `<!doctype html>
 <html>
@@ -77,28 +98,26 @@ function scalarHtml(specUrl) {
   <meta name="viewport" content="width=device-width, initial-scale=1" />
 </head>
 <body>
-  <script id="api-reference" data-url="${specUrl}"><\/script>
+  <script id="api-reference" data-url="${escapeHtmlAttr(specUrl)}"><\/script>
   <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"><\/script>
 </body>
 </html>`;
 }
 function openapi(routes, config) {
-	if (!extended) {
-		extendZodWithOpenApi(z);
-		extended = true;
-	}
 	const paths = {};
 	for (const descriptor of routes) {
 		const { method, path, config: routeConfig } = descriptor;
-		if (!method || path === "/**") continue;
+		if (!method || path.includes("*") || /:\w+[?+]/.test(path)) continue;
 		const openApiPath = toOpenApiPath(path);
 		if (!paths[openApiPath]) paths[openApiPath] = {};
 		const operation = { responses: {} };
 		const requestParams = {};
+		const inferredPathParams = extractPathParamNames(path);
 		if (routeConfig.request?.params) {
 			if (!(routeConfig.request.params instanceof z.ZodObject)) throw new Error(`params schema for ${method} ${path} must be a z.object()`);
+			assertPathParamsMatchPath(method, path, routeConfig.request.params);
 			requestParams.path = routeConfig.request.params;
-		}
+		} else if (inferredPathParams.length > 0) requestParams.path = z.object(Object.fromEntries(inferredPathParams.map((name) => [name, z.string()])));
 		if (routeConfig.request?.query) {
 			if (!(routeConfig.request.query instanceof z.ZodObject)) throw new Error(`query schema for ${method} ${path} must be a z.object()`);
 			requestParams.query = routeConfig.request.query;
@@ -108,7 +127,7 @@ function openapi(routes, config) {
 		if (routeConfig.response && Object.keys(routeConfig.response).length > 0) for (const [status, schema] of Object.entries(routeConfig.response)) {
 			const code = Number(status);
 			const entry = { description: STATUS_TEXT[code] ?? "Response" };
-			if (code !== 204) entry.content = { "application/json": { schema } };
+			if (operationCanHaveResponseBody(method, code)) entry.content = { "application/json": { schema } };
 			operation.responses[status] = entry;
 		}
 		else operation.responses = { 200: { description: "OK" } };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hectoday/openapi",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenAPI 3.1 spec generation for @hectoday/http routes.",
   "keywords": [
     "api",
@@ -21,7 +21,8 @@
     "directory": "packages/openapi"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "types": "./src/index.ts",
@@ -40,19 +41,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "zod-openapi": "^4.2.4"
+    "zod-openapi": "^5.4.6"
   },
   "devDependencies": {
-    "@hectoday/http": "^0.2.0",
+    "@hectoday/http": "^0.3.0",
     "@types/node": "^25.5.0",
     "bumpp": "^11.0.1",
     "typescript": "^5.9.3",
     "vite-plus": "latest",
     "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
-    "zod": "^3.24.0"
+    "zod": "^3.25.0"
   },
   "peerDependencies": {
-    "@hectoday/http": "^0.2.0",
-    "zod": "^3.24.0"
+    "@hectoday/http": "^0.3.0",
+    "zod": "^3.25.0"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,442 @@
+import { describe, expect, test } from "vite-plus/test";
+import * as z from "zod/v4";
+import { route } from "@hectoday/http";
+import { openapi } from "./index";
+import type { OpenApiConfig } from "./index";
+
+const securitySchemesTypecheck = {
+  bearerAuth: { type: "http", scheme: "bearer" },
+  apiKeyAuth: { type: "apiKey", name: "x-api-key", in: "header" },
+  oauthAuth: {
+    type: "oauth2",
+    flows: {
+      authorizationCode: {
+        authorizationUrl: "https://example.com/oauth/authorize",
+        tokenUrl: "https://example.com/oauth/token",
+        scopes: { read: "Read access" },
+      },
+    },
+  },
+  oidcAuth: {
+    type: "openIdConnect",
+    openIdConnectUrl: "https://example.com/.well-known/openid-configuration",
+  },
+} satisfies NonNullable<OpenApiConfig["securitySchemes"]>;
+
+void securitySchemesTypecheck;
+
+const invalidOAuth2SecurityScheme = {
+  brokenOAuth: {
+    type: "oauth2",
+    // @ts-expect-error oauth2 security schemes must define at least one flow
+    flows: {},
+  },
+} satisfies NonNullable<OpenApiConfig["securitySchemes"]>;
+
+const invalidAuthorizationCodeFlow = {
+  brokenAuthCode: {
+    type: "oauth2",
+    flows: {
+      // @ts-expect-error authorizationCode flow requires both authorizationUrl and tokenUrl
+      authorizationCode: {
+        scopes: { read: "Read access" },
+      },
+    },
+  },
+} satisfies NonNullable<OpenApiConfig["securitySchemes"]>;
+
+void invalidOAuth2SecurityScheme;
+void invalidAuthorizationCodeFlow;
+
+describe("openapi", () => {
+  test("generates spec from routes with schemas", () => {
+    const routes = [
+      route.get("/users", {
+        request: {
+          query: z.object({
+            page: z.coerce.number().int().min(1).default(1),
+          }),
+        },
+        response: {
+          200: z.object({ users: z.array(z.string()) }),
+        },
+        resolve: () => Response.json({ users: [] }),
+      }),
+      route.post("/users", {
+        request: {
+          body: z.object({
+            name: z.string(),
+            email: z.string().email(),
+          }),
+        },
+        response: {
+          201: z.object({ id: z.string() }),
+        },
+        resolve: () => Response.json({ id: "1" }, { status: 201 }),
+      }),
+      route.get("/users/:id", {
+        request: {
+          params: z.object({ id: z.string() }),
+        },
+        resolve: () => Response.json({ id: "1", name: "Alice" }),
+      }),
+    ];
+
+    const { spec, docs } = openapi(routes, {
+      info: { title: "Test API", version: "1.0.0" },
+    });
+
+    const specRoute = spec(route);
+    expect(specRoute.method).toBe("GET");
+    expect(specRoute.path).toBe("/openapi.json");
+
+    const docsRoute = docs(route);
+    expect(docsRoute.method).toBe("GET");
+    expect(docsRoute.path).toBe("/docs");
+  });
+
+  test("spec route serves JSON document", async () => {
+    const routes = [
+      route.get("/health", {
+        response: { 200: z.object({ ok: z.boolean() }) },
+        resolve: () => Response.json({ ok: true }),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Health API", version: "0.1.0" },
+    });
+
+    const specRoute = spec(route);
+    const response = await specRoute.config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    expect(response.status).toBe(200);
+    const doc = await response.json();
+    expect(doc.openapi).toBe("3.1.0");
+    expect(doc.info.title).toBe("Health API");
+    expect(doc.paths["/health"]).toBeDefined();
+    expect(doc.paths["/health"].get).toBeDefined();
+  });
+
+  test("docs route serves HTML", async () => {
+    const { docs } = openapi([], {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const docsRoute = docs(route);
+    const response = await docsRoute.config.resolve({
+      request: new Request("http://localhost/docs"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    expect(response.headers.get("content-type")).toBe("text/html");
+    const html = await response.text();
+    expect(html).toContain("@scalar/api-reference");
+    expect(html).toContain("/openapi.json");
+  });
+
+  test("infers string path parameters when no params schema is provided", async () => {
+    const routes = [
+      route.get("/users/:id", {
+        resolve: () => Response.json({ ok: true }),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    expect(doc.paths["/users/{id}"].get.parameters).toEqual([
+      expect.objectContaining({
+        in: "path",
+        name: "id",
+        required: true,
+      }),
+    ]);
+  });
+
+  test("throws when params schema does not match path parameters", () => {
+    expect(() =>
+      openapi(
+        [
+          route.get("/users/:id", {
+            request: {
+              params: z.object({ slug: z.string() }),
+            },
+            resolve: () => Response.json({ ok: true }),
+          }),
+        ],
+        { info: { title: "Test", version: "1.0.0" } },
+      ),
+    ).toThrow("params schema for GET /users/:id must define exactly these path params: id");
+  });
+
+  test("converts path params from :id to {id}", async () => {
+    const routes = [
+      route.get("/users/:userId/posts/:postId", {
+        request: {
+          params: z.object({ userId: z.string(), postId: z.string() }),
+        },
+        resolve: () => Response.json({}),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    expect(doc.paths["/users/{userId}/posts/{postId}"]).toBeDefined();
+  });
+
+  test("skips catch-all and methodless routes", async () => {
+    const routes = [
+      route.all("/catch", {
+        resolve: () => new Response("ok"),
+      }),
+      route.get("/real", {
+        resolve: () => Response.json({ ok: true }),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    expect(doc.paths["/catch"]).toBeUndefined();
+    expect(doc.paths["/real"]).toBeDefined();
+  });
+
+  test("skips named and nested wildcard paths", async () => {
+    const routes = [
+      route.get("/files/**", {
+        resolve: () => Response.json({ ok: true }),
+      }),
+      route.get("/files/**:path", {
+        resolve: () => Response.json({ ok: true }),
+      }),
+      route.get("/users/:id", {
+        request: { params: z.object({ id: z.string() }) },
+        resolve: () => Response.json({ ok: true }),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    expect(doc.paths["/files/**"]).toBeUndefined();
+    expect(doc.paths["/files/**:path"]).toBeUndefined();
+    expect(doc.paths["/users/{id}"]).toBeDefined();
+  });
+
+  test("custom spec and docs paths", () => {
+    const { spec, docs } = openapi([], {
+      info: { title: "Test", version: "1.0.0" },
+      specPath: "/api/spec.json",
+      docsPath: "/api/docs",
+    });
+
+    expect(spec(route).path).toBe("/api/spec.json");
+    expect(docs(route).path).toBe("/api/docs");
+  });
+
+  test("includes servers and tags in document", async () => {
+    const { spec } = openapi([], {
+      info: { title: "Test", version: "1.0.0" },
+      servers: [{ url: "https://api.example.com", description: "Production" }],
+      tags: [{ name: "users", description: "User operations" }],
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    expect(doc.servers).toEqual([{ url: "https://api.example.com", description: "Production" }]);
+    expect(doc.tags).toEqual([{ name: "users", description: "User operations" }]);
+  });
+
+  test("request body is included for POST routes", async () => {
+    const routes = [
+      route.post("/items", {
+        request: {
+          body: z.object({ name: z.string() }),
+        },
+        resolve: () => Response.json({}, { status: 201 }),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    const post = doc.paths["/items"].post;
+    expect(post.requestBody).toBeDefined();
+    expect(post.requestBody.content["application/json"]).toBeDefined();
+  });
+
+  test("omits content for status codes that cannot include a response body", async () => {
+    const routes = [
+      route.get("/cache", {
+        response: {
+          204: z.object({ ok: z.boolean() }),
+          205: z.object({ reset: z.boolean() }),
+          304: z.object({ cached: z.boolean() }),
+        },
+        resolve: () => new Response(null, { status: 204 }),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    const responses = doc.paths["/cache"].get.responses;
+    expect(responses["204"].content).toBeUndefined();
+    expect(responses["205"].content).toBeUndefined();
+    expect(responses["304"].content).toBeUndefined();
+  });
+
+  test("omits response content for HEAD operations", async () => {
+    const routes = [
+      route.head("/health", {
+        response: {
+          200: z.object({ ok: z.boolean() }),
+        },
+        resolve: () => new Response(null, { status: 200 }),
+      }),
+    ];
+
+    const { spec } = openapi(routes, {
+      info: { title: "Test", version: "1.0.0" },
+    });
+
+    const response = await spec(route).config.resolve({
+      request: new Request("http://localhost/openapi.json"),
+      input: {
+        ok: true,
+        params: {},
+        query: {},
+        body: undefined,
+        issues: [],
+        failed: [],
+      },
+      locals: {},
+    });
+
+    const doc = await response.json();
+    expect(doc.paths["/health"].head.responses["200"].content).toBeUndefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,350 @@
+import type { RouteDescriptor } from "@hectoday/http";
+import * as z from "zod/v4";
+import { createDocument } from "zod-openapi";
+import type { ZodOpenApiOperationObject } from "zod-openapi";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface OpenApiConfig {
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+    license?: { name: string; url?: string };
+  };
+  specPath?: string;
+  docsPath?: string;
+  servers?: Array<{ url: string; description?: string }>;
+  tags?: Array<{ name: string; description?: string }>;
+  security?: Array<Record<string, string[]>>;
+  securitySchemes?: Record<string, SecurityScheme>;
+}
+
+export type OAuth2Scopes = Record<string, string>;
+
+export type OAuth2ImplicitFlow = {
+  authorizationUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+
+export type OAuth2PasswordFlow = {
+  tokenUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+
+export type OAuth2ClientCredentialsFlow = {
+  tokenUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+
+export type OAuth2AuthorizationCodeFlow = {
+  authorizationUrl: string;
+  tokenUrl: string;
+  refreshUrl?: string;
+  scopes: OAuth2Scopes;
+};
+
+type OAuth2FlowMap = {
+  implicit: OAuth2ImplicitFlow;
+  password: OAuth2PasswordFlow;
+  clientCredentials: OAuth2ClientCredentialsFlow;
+  authorizationCode: OAuth2AuthorizationCodeFlow;
+};
+
+export type OAuth2Flows =
+  | { implicit: OAuth2FlowMap["implicit"] }
+  | { password: OAuth2FlowMap["password"] }
+  | { clientCredentials: OAuth2FlowMap["clientCredentials"] }
+  | { authorizationCode: OAuth2FlowMap["authorizationCode"] }
+  | ({ implicit: OAuth2FlowMap["implicit"] } & Partial<Omit<OAuth2FlowMap, "implicit">>)
+  | ({ password: OAuth2FlowMap["password"] } & Partial<Omit<OAuth2FlowMap, "password">>)
+  | ({
+      clientCredentials: OAuth2FlowMap["clientCredentials"];
+    } & Partial<Omit<OAuth2FlowMap, "clientCredentials">>)
+  | ({
+      authorizationCode: OAuth2FlowMap["authorizationCode"];
+    } & Partial<Omit<OAuth2FlowMap, "authorizationCode">>);
+
+export type SecurityScheme =
+  | {
+      type: "http";
+      scheme: string;
+      bearerFormat?: string;
+      description?: string;
+    }
+  | {
+      type: "apiKey";
+      name: string;
+      in: "query" | "header" | "cookie";
+      description?: string;
+    }
+  | {
+      type: "oauth2";
+      flows: OAuth2Flows;
+      description?: string;
+    }
+  | {
+      type: "openIdConnect";
+      openIdConnectUrl: string;
+      description?: string;
+    };
+
+export interface OpenApiResult {
+  /** Creates a GET route that serves the OpenAPI JSON document. */
+  spec: (route: { get: (path: string, config: any) => RouteDescriptor }) => RouteDescriptor;
+  /** Creates a GET route that serves the Scalar API reference UI. */
+  docs: (route: { get: (path: string, config: any) => RouteDescriptor }) => RouteDescriptor;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function extractPathParamNames(path: string): string[] {
+  return Array.from(path.matchAll(/:(\w+)/g), (match) => match[1]);
+}
+
+function toOpenApiPath(path: string): string {
+  return path.replace(/:(\w+)/g, "{$1}");
+}
+
+function getSchemaObjectKeys(schema: z.ZodObject<any>): string[] {
+  return Object.keys(schema.shape);
+}
+
+function assertPathParamsMatchPath(method: string, path: string, schema: z.ZodObject<any>): void {
+  const pathParamNames = extractPathParamNames(path);
+  const schemaParamNames = getSchemaObjectKeys(schema);
+
+  const hasExactMatch =
+    pathParamNames.length === schemaParamNames.length &&
+    pathParamNames.every((name) => schemaParamNames.includes(name));
+
+  if (hasExactMatch) return;
+
+  if (pathParamNames.length === 0) {
+    throw new Error(
+      `params schema for ${method} ${path} cannot define path params when the path has none`,
+    );
+  }
+
+  throw new Error(
+    `params schema for ${method} ${path} must define exactly these path params: ${pathParamNames.join(", ")}`,
+  );
+}
+
+function responseCanHaveBody(status: number): boolean {
+  return !(status >= 100 && status < 200) && status !== 204 && status !== 205 && status !== 304;
+}
+
+function operationCanHaveResponseBody(method: string, status: number): boolean {
+  return method.toUpperCase() !== "HEAD" && responseCanHaveBody(status);
+}
+
+const STATUS_TEXT: Record<number, string> = {
+  100: "Continue",
+  101: "Switching Protocols",
+  102: "Processing",
+  103: "Early Hints",
+  200: "OK",
+  201: "Created",
+  202: "Accepted",
+  203: "Non-Authoritative Information",
+  204: "No Content",
+  205: "Reset Content",
+  206: "Partial Content",
+  207: "Multi-Status",
+  208: "Already Reported",
+  226: "IM Used",
+  300: "Multiple Choices",
+  301: "Moved Permanently",
+  302: "Found",
+  303: "See Other",
+  304: "Not Modified",
+  307: "Temporary Redirect",
+  308: "Permanent Redirect",
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Content Too Large",
+  414: "URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a Teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required",
+};
+
+function escapeHtmlAttr(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function scalarHtml(specUrl: string): string {
+  return `<!doctype html>
+<html>
+<head>
+  <title>API Reference</title>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+  <script id="api-reference" data-url="${escapeHtmlAttr(specUrl)}"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+
+export function openapi(routes: RouteDescriptor[], config: OpenApiConfig): OpenApiResult {
+  const paths: Record<string, Record<string, ZodOpenApiOperationObject>> = {};
+
+  for (const descriptor of routes) {
+    const { method, path, config: routeConfig } = descriptor;
+
+    // Skip catch-all handlers (route.all) and paths that OpenAPI path
+    // templating cannot represent: wildcards (*, **), optional params
+    // (:name?), and one-or-more params (:name+).
+    if (!method || path.includes("*") || /:\w+[?+]/.test(path)) continue;
+
+    const openApiPath = toOpenApiPath(path);
+    if (!paths[openApiPath]) paths[openApiPath] = {};
+
+    const operation: ZodOpenApiOperationObject = {
+      responses: {},
+    };
+
+    // --- request params & query (must be z.object() schemas) ---
+    const requestParams: Record<string, z.ZodType> = {};
+    const inferredPathParams = extractPathParamNames(path);
+
+    if (routeConfig.request?.params) {
+      if (!(routeConfig.request.params instanceof z.ZodObject)) {
+        throw new Error(`params schema for ${method} ${path} must be a z.object()`);
+      }
+      assertPathParamsMatchPath(method, path, routeConfig.request.params);
+      requestParams.path = routeConfig.request.params;
+    } else if (inferredPathParams.length > 0) {
+      requestParams.path = z.object(
+        Object.fromEntries(inferredPathParams.map((name) => [name, z.string()])),
+      );
+    }
+
+    if (routeConfig.request?.query) {
+      if (!(routeConfig.request.query instanceof z.ZodObject)) {
+        throw new Error(`query schema for ${method} ${path} must be a z.object()`);
+      }
+      requestParams.query = routeConfig.request.query;
+    }
+
+    if (Object.keys(requestParams).length > 0) {
+      operation.requestParams = requestParams;
+    }
+
+    // --- request body ---
+    if (routeConfig.request?.body) {
+      operation.requestBody = {
+        content: {
+          "application/json": {
+            schema: routeConfig.request.body,
+          },
+        },
+      };
+    }
+
+    // --- responses ---
+    if (routeConfig.response && Object.keys(routeConfig.response).length > 0) {
+      for (const [status, schema] of Object.entries(routeConfig.response)) {
+        const code = Number(status);
+        const entry: Record<string, unknown> = {
+          description: STATUS_TEXT[code] ?? "Response",
+        };
+
+        // These HTTP statuses do not allow a response body.
+        if (operationCanHaveResponseBody(method, code)) {
+          entry.content = {
+            "application/json": { schema: schema as z.ZodType },
+          };
+        }
+
+        (operation.responses as Record<string, unknown>)[status] = entry;
+      }
+    } else {
+      operation.responses = {
+        200: { description: "OK" },
+      };
+    }
+
+    paths[openApiPath][method.toLowerCase()] = operation;
+  }
+
+  const specPath = config.specPath ?? "/openapi.json";
+  const docsPath = config.docsPath ?? "/docs";
+
+  const document = createDocument({
+    openapi: "3.1.0",
+    info: config.info,
+    servers: config.servers,
+    tags: config.tags,
+    security: config.security,
+    components: config.securitySchemes
+      ? { securitySchemes: config.securitySchemes as any }
+      : undefined,
+    paths,
+  });
+
+  return {
+    spec: (route) =>
+      route.get(specPath, {
+        resolve: () => Response.json(document),
+      }),
+    docs: (route) =>
+      route.get(docsPath, {
+        resolve: () =>
+          new Response(scalarHtml(specPath), {
+            headers: { "content-type": "text/html" },
+          }),
+      }),
+  };
+}