@cinnabun/openapi 0.0.1

package/src/generator/openapi-generator.ts

@@ -0,0 +1,213 @@
+import type { OpenApiModuleOptions } from "../interfaces/openapi-options.js";
+import type { ScannedRoute } from "./route-scanner.js";
+import { convertZodSchema } from "./schema-converter.js";
+
+export interface OpenApiSpec {
+  openapi: string;
+  info: { title: string; description?: string; version: string };
+  servers?: { url: string; description?: string }[];
+  tags?: { name: string; description?: string }[];
+  paths: Record<string, Record<string, any>>;
+  components: {
+    schemas: Record<string, any>;
+    securitySchemes?: Record<string, any>;
+  };
+  security?: Record<string, string[]>[];
+}
+
+export function generateSpec(
+  options: OpenApiModuleOptions,
+  routes: ScannedRoute[],
+): OpenApiSpec {
+  const spec: OpenApiSpec = {
+    openapi: "3.1.0",
+    info: {
+      title: options.title,
+      version: options.version,
+    },
+    paths: {},
+    components: {
+      schemas: {},
+    },
+  };
+
+  if (options.description) {
+    spec.info.description = options.description;
+  }
+
+  if (options.servers?.length) {
+    spec.servers = options.servers;
+  }
+
+  // Collect all tags from options + routes
+  const tagSet = new Map<string, string | undefined>();
+  if (options.tags) {
+    for (const t of options.tags) {
+      tagSet.set(t.name, t.description);
+    }
+  }
+  for (const route of routes) {
+    for (const tag of route.tags) {
+      if (!tagSet.has(tag)) tagSet.set(tag, undefined);
+    }
+  }
+  if (tagSet.size > 0) {
+    spec.tags = Array.from(tagSet.entries()).map(([name, description]) =>
+      description ? { name, description } : { name },
+    );
+  }
+
+  // Bearer auth
+  if (options.bearerAuth) {
+    spec.components.securitySchemes = {
+      bearerAuth: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT",
+      },
+    };
+    spec.security = [{ bearerAuth: [] }];
+  }
+
+  // Build paths
+  for (const route of routes) {
+    const openApiPath = convertPathParams(route.fullPath);
+    const method = route.httpMethod.toLowerCase();
+
+    if (!spec.paths[openApiPath]) {
+      spec.paths[openApiPath] = {};
+    }
+
+    const operation: Record<string, any> = {};
+
+    // Tags
+    if (route.tags.length > 0) {
+      operation.tags = route.tags;
+    }
+
+    // Operation metadata
+    if (route.operation) {
+      if (route.operation.summary) operation.summary = route.operation.summary;
+      if (route.operation.description)
+        operation.description = route.operation.description;
+      if (route.operation.deprecated) operation.deprecated = true;
+    }
+
+    // Parameters from @Param and @Query
+    const parameters = buildParameters(route);
+    if (parameters.length > 0) {
+      operation.parameters = parameters;
+    }
+
+    // Request body from validation schema
+    if (route.validationSchema?.body) {
+      const schemaName = `${route.controllerName}_${route.methodKey}_Body`;
+      const { jsonSchema, componentName } = convertZodSchema(
+        route.validationSchema.body,
+        schemaName,
+      );
+      spec.components.schemas[componentName] = jsonSchema;
+
+      operation.requestBody = {
+        required: true,
+        content: {
+          "application/json": {
+            schema: { $ref: `#/components/schemas/${componentName}` },
+          },
+        },
+      };
+    }
+
+    // Responses
+    operation.responses = buildResponses(route);
+
+    spec.paths[openApiPath][method] = operation;
+  }
+
+  return spec;
+}
+
+function convertPathParams(path: string): string {
+  // Convert Express-style :param to OpenAPI {param}
+  return path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}");
+}
+
+function buildParameters(route: ScannedRoute): any[] {
+  const parameters: any[] = [];
+
+  for (const param of route.params) {
+    if (param.source === "param" && param.name) {
+      parameters.push({
+        name: param.name,
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+      });
+    } else if (param.source === "query" && param.name) {
+      parameters.push({
+        name: param.name,
+        in: "query",
+        required: false,
+        schema: { type: "string" },
+      });
+    }
+  }
+
+  // Also add query schema from validation if available
+  if (route.validationSchema?.query) {
+    const { jsonSchema } = convertZodSchema(route.validationSchema.query);
+    if (
+      jsonSchema.type === "object" &&
+      jsonSchema.properties &&
+      typeof jsonSchema.properties === "object"
+    ) {
+      const required = (jsonSchema.required as string[]) ?? [];
+      for (const [name, propSchema] of Object.entries(
+        jsonSchema.properties as Record<string, any>,
+      )) {
+        // Skip if already added from @Query decorator
+        if (parameters.some((p) => p.name === name && p.in === "query"))
+          continue;
+        parameters.push({
+          name,
+          in: "query",
+          required: required.includes(name),
+          schema: propSchema,
+        });
+      }
+    }
+  }
+
+  return parameters;
+}
+
+function buildResponses(route: ScannedRoute): Record<string, any> {
+  const responses: Record<string, any> = {};
+
+  if (route.responses.length > 0) {
+    for (const resp of route.responses) {
+      responses[String(resp.status)] = {
+        description: resp.description,
+      };
+    }
+  } else {
+    // Default response based on HTTP code or method
+    const code = route.httpCode ?? getDefaultStatusCode(route.httpMethod);
+    responses[String(code)] = {
+      description: "Successful response",
+    };
+  }
+
+  return responses;
+}
+
+function getDefaultStatusCode(method: string): number {
+  switch (method) {
+    case "POST":
+      return 201;
+    case "DELETE":
+      return 204;
+    default:
+      return 200;
+  }
+}

package/src/generator/route-scanner.ts

@@ -0,0 +1,92 @@
+import {
+  metadataStorage,
+  type RouteMetadata,
+  type ParamMetadata,
+  type HttpMethod,
+} from "@cinnabun/core";
+import {
+  openApiMetadataStorage,
+  type ApiOperationMetadata,
+  type ApiResponseMetadata,
+} from "../metadata/openapi-storage.js";
+
+export interface ScannedRoute {
+  httpMethod: HttpMethod;
+  fullPath: string;
+  controllerName: string;
+  methodKey: string;
+  params: ParamMetadata[];
+  validationSchema?: { body?: any; query?: any; params?: any };
+  httpCode?: number;
+  operation?: ApiOperationMetadata;
+  responses: ApiResponseMetadata[];
+  tags: string[];
+}
+
+export function scanRoutes(
+  excludeControllers?: Function[],
+): ScannedRoute[] {
+  const routes: ScannedRoute[] = [];
+  const excludeNames = new Set(
+    (excludeControllers ?? []).map((c) => c.name),
+  );
+
+  for (const route of metadataStorage.routes) {
+    const controllerName = route.target.name;
+
+    // Skip excluded controllers (e.g. OpenApiController itself)
+    if (excludeNames.has(controllerName)) continue;
+
+    const basePath = metadataStorage.getControllerPath(route.target);
+    const fullPath = normalizePath(basePath + route.path);
+
+    const params = metadataStorage.getParamsFor(
+      route.target,
+      route.methodKey,
+    );
+
+    const validationSchema = metadataStorage.getValidationSchema(
+      route.target,
+      route.methodKey,
+    );
+
+    const httpCode = metadataStorage.getHttpCode(
+      route.target,
+      route.methodKey,
+    );
+
+    const operation = openApiMetadataStorage.getOperation(
+      route.target,
+      route.methodKey,
+    );
+
+    const responses = openApiMetadataStorage.getResponses(
+      route.target,
+      route.methodKey,
+    );
+
+    const tags = openApiMetadataStorage.getTags(route.target);
+
+    routes.push({
+      httpMethod: route.httpMethod,
+      fullPath,
+      controllerName,
+      methodKey: route.methodKey,
+      params,
+      validationSchema,
+      httpCode,
+      operation,
+      responses,
+      tags,
+    });
+  }
+
+  return routes;
+}
+
+function normalizePath(path: string): string {
+  // Ensure leading slash, collapse double slashes
+  let normalized = "/" + path.replace(/\/+/g, "/").replace(/^\/|\/$/g, "");
+  if (normalized === "") normalized = "/";
+  return normalized;
+}

package/src/generator/schema-converter.ts

@@ -0,0 +1,21 @@
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+export interface ConvertedSchema {
+  jsonSchema: Record<string, unknown>;
+  componentName: string;
+}
+
+export function convertZodSchema(
+  schema: any,
+  name?: string,
+): ConvertedSchema {
+  const raw = zodToJsonSchema(schema, { target: "openApi3" });
+  const jsonSchema = { ...raw } as Record<string, unknown>;
+
+  // Remove $schema key — not needed inside OpenAPI spec
+  delete jsonSchema.$schema;
+
+  const componentName = name ?? "Schema";
+
+  return { jsonSchema, componentName };
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { OpenApiModule } from "./openapi.module.js";
+export type { OpenApiModuleOptions } from "./interfaces/openapi-options.js";
+export { ApiOperation } from "./decorators/api-operation.js";
+export { ApiResponse } from "./decorators/api-response.js";
+export { ApiTags } from "./decorators/api-tags.js";
+export { ApiProperty } from "./decorators/api-property.js";
+export type { ApiOperationMetadata, ApiResponseMetadata, ApiPropertyMetadata } from "./metadata/openapi-storage.js";
+export { openApiMetadataStorage } from "./metadata/openapi-storage.js";
+export { scanRoutes } from "./generator/route-scanner.js";
+export type { ScannedRoute } from "./generator/route-scanner.js";
+export { generateSpec } from "./generator/openapi-generator.js";
+export type { OpenApiSpec } from "./generator/openapi-generator.js";
+export { convertZodSchema } from "./generator/schema-converter.js";
+export type { ConvertedSchema } from "./generator/schema-converter.js";

package/src/interfaces/openapi-options.ts

@@ -0,0 +1,11 @@
+export interface OpenApiModuleOptions {
+  title: string;
+  description?: string;
+  version: string;
+  basePath?: string;
+  docsPath?: string;
+  jsonPath?: string;
+  servers?: { url: string; description?: string }[];
+  tags?: { name: string; description?: string }[];
+  bearerAuth?: boolean;
+}

package/src/metadata/openapi-storage.ts

@@ -0,0 +1,108 @@
+export interface ApiOperationMetadata {
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+}
+
+export interface ApiResponseMetadata {
+  status: number;
+  description: string;
+  type?: any;
+}
+
+export interface ApiPropertyMetadata {
+  type?: string;
+  required?: boolean;
+  example?: unknown;
+  description?: string;
+}
+
+export interface CurrentUserParamMetadata {
+  target: Function;
+  methodKey: string;
+  parameterIndex: number;
+}
+
+class OpenApiMetadataStorage {
+  private operations = new Map<string, ApiOperationMetadata>();
+  private responses = new Map<string, ApiResponseMetadata[]>();
+  private tags = new Map<Function, string[]>();
+  private properties = new Map<string, Map<string, ApiPropertyMetadata>>();
+
+  private key(target: Function, methodKey: string): string {
+    return `${target.name}.${methodKey}`;
+  }
+
+  private classKey(target: Function, propertyKey: string): string {
+    return `${target.name}.${propertyKey}`;
+  }
+
+  setOperation(
+    target: Function,
+    methodKey: string,
+    metadata: ApiOperationMetadata,
+  ): void {
+    this.operations.set(this.key(target, methodKey), metadata);
+  }
+
+  getOperation(
+    target: Function,
+    methodKey: string,
+  ): ApiOperationMetadata | undefined {
+    return this.operations.get(this.key(target, methodKey));
+  }
+
+  addResponse(
+    target: Function,
+    methodKey: string,
+    metadata: ApiResponseMetadata,
+  ): void {
+    const k = this.key(target, methodKey);
+    const existing = this.responses.get(k) ?? [];
+    existing.push(metadata);
+    this.responses.set(k, existing);
+  }
+
+  getResponses(
+    target: Function,
+    methodKey: string,
+  ): ApiResponseMetadata[] {
+    return this.responses.get(this.key(target, methodKey)) ?? [];
+  }
+
+  setTags(target: Function, tags: string[]): void {
+    this.tags.set(target, tags);
+  }
+
+  getTags(target: Function): string[] {
+    return this.tags.get(target) ?? [];
+  }
+
+  setProperty(
+    target: Function,
+    propertyKey: string,
+    metadata: ApiPropertyMetadata,
+  ): void {
+    const k = target.name ?? target.constructor?.name;
+    if (!this.properties.has(k)) {
+      this.properties.set(k, new Map());
+    }
+    this.properties.get(k)!.set(propertyKey, metadata);
+  }
+
+  getProperties(
+    target: Function,
+  ): Map<string, ApiPropertyMetadata> | undefined {
+    const k = target.name ?? target.constructor?.name;
+    return this.properties.get(k);
+  }
+
+  reset(): void {
+    this.operations.clear();
+    this.responses.clear();
+    this.tags.clear();
+    this.properties.clear();
+  }
+}
+
+export const openApiMetadataStorage = new OpenApiMetadataStorage();

package/src/openapi.module.ts

@@ -0,0 +1,91 @@
+import { Module, RestController, GetMapping } from "@cinnabun/core";
+import type { OpenApiModuleOptions } from "./interfaces/openapi-options.js";
+import { scanRoutes } from "./generator/route-scanner.js";
+import { generateSpec, type OpenApiSpec } from "./generator/openapi-generator.js";
+
+let moduleOptions: OpenApiModuleOptions | null = null;
+let cachedSpec: OpenApiSpec | null = null;
+
+export class OpenApiModule {
+  static forRoot(options: OpenApiModuleOptions): Function {
+    moduleOptions = options;
+    cachedSpec = null;
+
+    const docsPath = options.docsPath ?? "/api-docs";
+    const jsonPath = options.jsonPath ?? `${docsPath}/json`;
+    const basePath = docsPath.replace(/\/$/, "") || "/";
+    const specRoute = jsonPath.startsWith(basePath)
+      ? jsonPath.slice(basePath.length) || "/json"
+      : "/json";
+
+    // Dynamically create controller with configured paths
+    @RestController(docsPath)
+    class DynamicOpenApiController {
+      @GetMapping(specRoute.startsWith("/") ? specRoute : `/${specRoute}`)
+      getSpec() {
+        if (!cachedSpec) {
+          const routes = scanRoutes([DynamicOpenApiController]);
+          cachedSpec = generateSpec(options, routes);
+        }
+        return cachedSpec;
+      }
+
+      @GetMapping("/")
+      getSwaggerUI() {
+        const html = buildSwaggerUIHtml(options.title, jsonPath);
+        return new Response(html, {
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
+    }
+
+    @Module({
+      controllers: [DynamicOpenApiController],
+      providers: [],
+      exports: [],
+    })
+    class OpenApiDynamicModule {}
+
+    return OpenApiDynamicModule;
+  }
+
+  static getOptions(): OpenApiModuleOptions {
+    if (!moduleOptions) {
+      throw new Error(
+        "OpenApiModule not initialized. Call OpenApiModule.forRoot() first.",
+      );
+    }
+    return moduleOptions;
+  }
+
+  static resetCache(): void {
+    cachedSpec = null;
+  }
+}
+
+function buildSwaggerUIHtml(title: string, specUrl: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title} - API Docs</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: '${specUrl}',
+      dom_id: '#swagger-ui',
+      presets: [
+        SwaggerUIBundle.presets.apis,
+        SwaggerUIBundle.SwaggerUIStandalonePreset
+      ],
+      layout: 'BaseLayout'
+    });
+  </script>
+</body>
+</html>`;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "declaration": true,
+    "types": ["bun"]
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}