@cinnabun/openapi 0.0.1

package/dist/generator/openapi-generator.js

@@ -0,0 +1,166 @@
+import { convertZodSchema } from "./schema-converter.js";
+export function generateSpec(options, routes) {
+    const spec = {
+        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();
+    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 = {};
+        // 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) {
+    // Convert Express-style :param to OpenAPI {param}
+    return path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}");
+}
+function buildParameters(route) {
+    const parameters = [];
+    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 ?? [];
+            for (const [name, propSchema] of Object.entries(jsonSchema.properties)) {
+                // 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) {
+    const responses = {};
+    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) {
+    switch (method) {
+        case "POST":
+            return 201;
+        case "DELETE":
+            return 204;
+        default:
+            return 200;
+    }
+}

package/dist/generator/route-scanner.d.ts

@@ -0,0 +1,19 @@
+import { type ParamMetadata, type HttpMethod } from "@cinnabun/core";
+import { 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 declare function scanRoutes(excludeControllers?: Function[]): ScannedRoute[];

package/dist/generator/route-scanner.js

@@ -0,0 +1,40 @@
+import { metadataStorage, } from "@cinnabun/core";
+import { openApiMetadataStorage, } from "../metadata/openapi-storage.js";
+export function scanRoutes(excludeControllers) {
+    const routes = [];
+    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) {
+    // Ensure leading slash, collapse double slashes
+    let normalized = "/" + path.replace(/\/+/g, "/").replace(/^\/|\/$/g, "");
+    if (normalized === "")
+        normalized = "/";
+    return normalized;
+}

package/dist/generator/schema-converter.d.ts

@@ -0,0 +1,5 @@
+export interface ConvertedSchema {
+    jsonSchema: Record<string, unknown>;
+    componentName: string;
+}
+export declare function convertZodSchema(schema: any, name?: string): ConvertedSchema;

package/dist/generator/schema-converter.js

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

package/dist/index.d.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/dist/index.js

@@ -0,0 +1,9 @@
+export { OpenApiModule } from "./openapi.module.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 { openApiMetadataStorage } from "./metadata/openapi-storage.js";
+export { scanRoutes } from "./generator/route-scanner.js";
+export { generateSpec } from "./generator/openapi-generator.js";
+export { convertZodSchema } from "./generator/schema-converter.js";

package/dist/interfaces/openapi-options.d.ts

@@ -0,0 +1,17 @@
+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/dist/interfaces/openapi-options.js

@@ -0,0 +1 @@
+export {};

package/dist/metadata/openapi-storage.d.ts

@@ -0,0 +1,40 @@
+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;
+}
+declare class OpenApiMetadataStorage {
+    private operations;
+    private responses;
+    private tags;
+    private properties;
+    private key;
+    private classKey;
+    setOperation(target: Function, methodKey: string, metadata: ApiOperationMetadata): void;
+    getOperation(target: Function, methodKey: string): ApiOperationMetadata | undefined;
+    addResponse(target: Function, methodKey: string, metadata: ApiResponseMetadata): void;
+    getResponses(target: Function, methodKey: string): ApiResponseMetadata[];
+    setTags(target: Function, tags: string[]): void;
+    getTags(target: Function): string[];
+    setProperty(target: Function, propertyKey: string, metadata: ApiPropertyMetadata): void;
+    getProperties(target: Function): Map<string, ApiPropertyMetadata> | undefined;
+    reset(): void;
+}
+export declare const openApiMetadataStorage: OpenApiMetadataStorage;
+export {};

package/dist/metadata/openapi-storage.js

@@ -0,0 +1,51 @@
+class OpenApiMetadataStorage {
+    operations = new Map();
+    responses = new Map();
+    tags = new Map();
+    properties = new Map();
+    key(target, methodKey) {
+        return `${target.name}.${methodKey}`;
+    }
+    classKey(target, propertyKey) {
+        return `${target.name}.${propertyKey}`;
+    }
+    setOperation(target, methodKey, metadata) {
+        this.operations.set(this.key(target, methodKey), metadata);
+    }
+    getOperation(target, methodKey) {
+        return this.operations.get(this.key(target, methodKey));
+    }
+    addResponse(target, methodKey, metadata) {
+        const k = this.key(target, methodKey);
+        const existing = this.responses.get(k) ?? [];
+        existing.push(metadata);
+        this.responses.set(k, existing);
+    }
+    getResponses(target, methodKey) {
+        return this.responses.get(this.key(target, methodKey)) ?? [];
+    }
+    setTags(target, tags) {
+        this.tags.set(target, tags);
+    }
+    getTags(target) {
+        return this.tags.get(target) ?? [];
+    }
+    setProperty(target, propertyKey, metadata) {
+        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) {
+        const k = target.name ?? target.constructor?.name;
+        return this.properties.get(k);
+    }
+    reset() {
+        this.operations.clear();
+        this.responses.clear();
+        this.tags.clear();
+        this.properties.clear();
+    }
+}
+export const openApiMetadataStorage = new OpenApiMetadataStorage();

package/dist/openapi.module.d.ts

@@ -0,0 +1,6 @@
+import type { OpenApiModuleOptions } from "./interfaces/openapi-options.js";
+export declare class OpenApiModule {
+    static forRoot(options: OpenApiModuleOptions): Function;
+    static getOptions(): OpenApiModuleOptions;
+    static resetCache(): void;
+}

package/dist/openapi.module.js

@@ -0,0 +1,103 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var DynamicOpenApiController_1;
+import { Module, RestController, GetMapping } from "@cinnabun/core";
+import { scanRoutes } from "./generator/route-scanner.js";
+import { generateSpec } from "./generator/openapi-generator.js";
+let moduleOptions = null;
+let cachedSpec = null;
+export class OpenApiModule {
+    static forRoot(options) {
+        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
+        let DynamicOpenApiController = DynamicOpenApiController_1 = class DynamicOpenApiController {
+            getSpec() {
+                if (!cachedSpec) {
+                    const routes = scanRoutes([DynamicOpenApiController_1]);
+                    cachedSpec = generateSpec(options, routes);
+                }
+                return cachedSpec;
+            }
+            getSwaggerUI() {
+                const html = buildSwaggerUIHtml(options.title, jsonPath);
+                return new Response(html, {
+                    headers: { "Content-Type": "text/html; charset=utf-8" },
+                });
+            }
+        };
+        __decorate([
+            GetMapping(specRoute.startsWith("/") ? specRoute : `/${specRoute}`),
+            __metadata("design:type", Function),
+            __metadata("design:paramtypes", []),
+            __metadata("design:returntype", void 0)
+        ], DynamicOpenApiController.prototype, "getSpec", null);
+        __decorate([
+            GetMapping("/"),
+            __metadata("design:type", Function),
+            __metadata("design:paramtypes", []),
+            __metadata("design:returntype", void 0)
+        ], DynamicOpenApiController.prototype, "getSwaggerUI", null);
+        DynamicOpenApiController = DynamicOpenApiController_1 = __decorate([
+            RestController(docsPath)
+        ], DynamicOpenApiController);
+        let OpenApiDynamicModule = class OpenApiDynamicModule {
+        };
+        OpenApiDynamicModule = __decorate([
+            Module({
+                controllers: [DynamicOpenApiController],
+                providers: [],
+                exports: [],
+            })
+        ], OpenApiDynamicModule);
+        return OpenApiDynamicModule;
+    }
+    static getOptions() {
+        if (!moduleOptions) {
+            throw new Error("OpenApiModule not initialized. Call OpenApiModule.forRoot() first.");
+        }
+        return moduleOptions;
+    }
+    static resetCache() {
+        cachedSpec = null;
+    }
+}
+function buildSwaggerUIHtml(title, specUrl) {
+    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/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@cinnabun/openapi",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "@cinnabun/core": "^0.0.3"
+  },
+  "dependencies": {
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@cinnabun/core": "workspace:*",
+    "@types/bun": "latest",
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^5.9.3",
+    "zod": "^3.24.0"
+  }
+}

package/src/decorators/api-operation.ts

@@ -0,0 +1,16 @@
+import {
+  openApiMetadataStorage,
+  type ApiOperationMetadata,
+} from "../metadata/openapi-storage.js";
+
+export function ApiOperation(
+  metadata: ApiOperationMetadata,
+): MethodDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    openApiMetadataStorage.setOperation(
+      target.constructor,
+      propertyKey as string,
+      metadata,
+    );
+  };
+}

package/src/decorators/api-property.ts

@@ -0,0 +1,16 @@
+import {
+  openApiMetadataStorage,
+  type ApiPropertyMetadata,
+} from "../metadata/openapi-storage.js";
+
+export function ApiProperty(
+  metadata: ApiPropertyMetadata = {},
+): PropertyDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    openApiMetadataStorage.setProperty(
+      target.constructor,
+      propertyKey as string,
+      metadata,
+    );
+  };
+}

package/src/decorators/api-response.ts

@@ -0,0 +1,14 @@
+import { openApiMetadataStorage } from "../metadata/openapi-storage.js";
+
+export function ApiResponse(
+  status: number,
+  metadata: { description: string; type?: any },
+): MethodDecorator {
+  return (target: any, propertyKey: string | symbol) => {
+    openApiMetadataStorage.addResponse(
+      target.constructor,
+      propertyKey as string,
+      { status, ...metadata },
+    );
+  };
+}

package/src/decorators/api-tags.ts

@@ -0,0 +1,7 @@
+import { openApiMetadataStorage } from "../metadata/openapi-storage.js";
+
+export function ApiTags(...tags: string[]): ClassDecorator {
+  return (target: any) => {
+    openApiMetadataStorage.setTags(target, tags);
+  };
+}