@cinnabun/openapi 0.0.1

package/__tests__/openapi-generator.test.ts

@@ -0,0 +1,194 @@
+import "reflect-metadata";
+import { describe, it, expect, afterEach } from "bun:test";
+import {
+  RestController,
+  GetMapping,
+  PostMapping,
+  Param,
+  HttpCode,
+  metadataStorage,
+} from "@cinnabun/core";
+import { z } from "zod";
+import { Validate } from "@cinnabun/core";
+import { ApiTags, ApiOperation, ApiResponse } from "../src/index.js";
+import { scanRoutes } from "../src/generator/route-scanner.js";
+import { generateSpec } from "../src/generator/openapi-generator.js";
+import { openApiMetadataStorage } from "../src/metadata/openapi-storage.js";
+
+afterEach(() => {
+  openApiMetadataStorage.reset();
+});
+
+describe("openapi-generator", () => {
+  it("generates valid OpenAPI 3.1 spec structure", () => {
+    @RestController("/api/v1")
+    @ApiTags("Users")
+    class OpenApiSpecUserController {
+      @GetMapping("/")
+      @ApiOperation({ summary: "List users" })
+      @ApiResponse(200, { description: "List of users" })
+      findAll() {
+        return [];
+      }
+    }
+
+    const routes = scanRoutes();
+    const options = {
+      title: "Test API",
+      version: "1.0.0",
+    };
+
+    const spec = generateSpec(options, routes);
+
+    expect(spec.openapi).toBe("3.1.0");
+    expect(spec.info).toEqual({
+      title: "Test API",
+      version: "1.0.0",
+    });
+    expect(spec.paths).toBeDefined();
+    expect(typeof spec.paths).toBe("object");
+    expect(spec.components).toBeDefined();
+    expect(spec.components.schemas).toBeDefined();
+  });
+
+  it("generates paths from route registrations", () => {
+    @RestController("/items")
+    class ItemController {
+      @GetMapping("/")
+      list() {
+        return [];
+      }
+
+      @GetMapping("/:id")
+      get(@Param("id") id: string) {
+        return { id };
+      }
+
+      @PostMapping("/")
+      @HttpCode(201)
+      create() {
+        return {};
+      }
+    }
+
+    const routes = scanRoutes();
+    const spec = generateSpec(
+      { title: "API", version: "1.0.0" },
+      routes,
+    );
+
+    expect(spec.paths["/items"]).toBeDefined();
+    expect(spec.paths["/items"].get).toBeDefined();
+    expect(spec.paths["/items"].post).toBeDefined();
+
+    expect(spec.paths["/items/{id}"]).toBeDefined();
+    expect(spec.paths["/items/{id}"].get).toBeDefined();
+  });
+
+  it("generates parameters from @Param and @Query", () => {
+    @RestController("/openapi-users")
+    class OpenApiParamUserController {
+      @GetMapping("/:id")
+      get(@Param("id") id: string) {
+        return { id };
+      }
+    }
+
+    const routes = scanRoutes();
+    const spec = generateSpec(
+      { title: "API", version: "1.0.0" },
+      routes,
+    );
+
+    const getOp = spec.paths["/openapi-users/{id}"]?.get;
+    expect(getOp).toBeDefined();
+    expect(getOp!.parameters).toBeDefined();
+    expect(getOp!.parameters).toHaveLength(1);
+    expect(getOp!.parameters![0]).toMatchObject({
+      name: "id",
+      in: "path",
+      required: true,
+      schema: { type: "string" },
+    });
+  });
+
+  it("generates requestBody from @Validate body schema", () => {
+    const CreateUserSchema = z.object({
+      name: z.string(),
+      email: z.string().email(),
+    });
+
+    @RestController("/openapi-create-users")
+    class OpenApiCreateUserController {
+      @PostMapping("/")
+      @Validate({ body: CreateUserSchema })
+      create() {
+        return {};
+      }
+    }
+
+    const routes = scanRoutes();
+    const spec = generateSpec(
+      { title: "API", version: "1.0.0" },
+      routes,
+    );
+
+    const postOp = spec.paths["/openapi-create-users"]?.post;
+    expect(postOp).toBeDefined();
+    expect(postOp!.requestBody).toBeDefined();
+    expect(postOp!.requestBody!.required).toBe(true);
+    expect(postOp!.requestBody!.content).toBeDefined();
+    expect(postOp!.requestBody!.content!["application/json"]).toBeDefined();
+    expect(postOp!.requestBody!.content!["application/json"].schema).toHaveProperty("$ref");
+  });
+
+  it("generates responses from @ApiResponse and @HttpCode", () => {
+    @RestController("/openapi-response-users")
+    class OpenApiResponseUserController {
+      @GetMapping("/")
+      @ApiResponse(200, { description: "List of users" })
+      list() {
+        return [];
+      }
+
+      @PostMapping("/")
+      @HttpCode(201)
+      create() {
+        return {};
+      }
+    }
+
+    const routes = scanRoutes();
+    const spec = generateSpec(
+      { title: "API", version: "1.0.0" },
+      routes,
+    );
+
+    const getOp = spec.paths["/openapi-response-users"]?.get;
+    expect(getOp!.responses["200"]).toBeDefined();
+    expect(getOp!.responses["200"].description).toBe("List of users");
+
+    const postOp = spec.paths["/openapi-response-users"]?.post;
+    expect(postOp!.responses["201"]).toBeDefined();
+  });
+
+  it("adds bearer auth security scheme when bearerAuth is true", () => {
+    const routes = scanRoutes();
+    const spec = generateSpec(
+      {
+        title: "API",
+        version: "1.0.0",
+        bearerAuth: true,
+      },
+      routes,
+    );
+
+    expect(spec.components.securitySchemes).toBeDefined();
+    expect(spec.components.securitySchemes!.bearerAuth).toEqual({
+      type: "http",
+      scheme: "bearer",
+      bearerFormat: "JWT",
+    });
+    expect(spec.security).toEqual([{ bearerAuth: [] }]);
+  });
+});

package/__tests__/openapi-module.test.ts

@@ -0,0 +1,115 @@
+import "reflect-metadata";
+import { describe, it, expect, afterEach } from "bun:test";
+import {
+  CinnabunApplication,
+  CinnabunApp,
+  CinnabunFactory,
+  RestController,
+  GetMapping,
+} from "@cinnabun/core";
+import { OpenApiModule } from "../src/openapi.module.js";
+
+let app: CinnabunApplication | null = null;
+
+afterEach(async () => {
+  if (app) {
+    await app.close();
+    app = null;
+  }
+  OpenApiModule.resetCache?.();
+});
+
+function url(path: string): string {
+  return `http://localhost:${app!.getPort()}${path}`;
+}
+
+describe("OpenApiModule", () => {
+  it("serves Swagger UI HTML at docs path", async () => {
+    const OpenApiMod = OpenApiModule.forRoot({
+      title: "Test API",
+      version: "1.0.0",
+      docsPath: "/api-docs",
+    });
+
+    @CinnabunApp({ port: 0, scanPaths: [], imports: [OpenApiMod] })
+    @RestController("/api")
+    class App {
+      @GetMapping("/")
+      index() {
+        return { message: "ok" };
+      }
+    }
+
+    app = await CinnabunFactory.run(App);
+
+    const res = await fetch(url("/api-docs"));
+    expect(res.status).toBe(200);
+
+    const html = await res.text();
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).toContain("swagger-ui");
+    expect(html).toContain("Test API");
+    expect(res.headers.get("content-type")).toContain("text/html");
+  });
+
+  it("serves OpenAPI JSON spec at json path", async () => {
+    const OpenApiMod = OpenApiModule.forRoot({
+      title: "Test API",
+      version: "1.0.0",
+      docsPath: "/api-docs",
+      jsonPath: "/api-docs/json",
+    });
+
+    @CinnabunApp({ port: 0, scanPaths: [], imports: [OpenApiMod] })
+    @RestController("/api")
+    class App {
+      @GetMapping("/")
+      index() {
+        return { message: "ok" };
+      }
+    }
+
+    app = await CinnabunFactory.run(App);
+
+    const res = await fetch(url("/api-docs/json"));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/json");
+
+    const spec = (await res.json()) as Record<string, unknown>;
+    expect(spec.openapi).toBe("3.1.0");
+    expect(spec.info).toEqual({
+      title: "Test API",
+      version: "1.0.0",
+    });
+    expect(spec.paths).toBeDefined();
+    expect(spec.paths!["/api"]).toBeDefined();
+  });
+
+  it("uses custom docs path when configured", async () => {
+    const OpenApiMod = OpenApiModule.forRoot({
+      title: "Custom API",
+      version: "2.0.0",
+      docsPath: "/docs",
+      jsonPath: "/docs/spec",
+    });
+
+    @CinnabunApp({ port: 0, scanPaths: [], imports: [OpenApiMod] })
+    @RestController()
+    class App {
+      @GetMapping("/")
+      index() {
+        return {};
+      }
+    }
+
+    app = await CinnabunFactory.run(App);
+
+    const docsRes = await fetch(url("/docs"));
+    expect(docsRes.status).toBe(200);
+
+    const jsonRes = await fetch(url("/docs/spec"));
+    expect(jsonRes.status).toBe(200);
+    const spec = (await jsonRes.json()) as Record<string, unknown>;
+    expect(spec.info?.title).toBe("Custom API");
+  });
+});

package/__tests__/route-scanner.test.ts

@@ -0,0 +1,120 @@
+import "reflect-metadata";
+import { describe, it, expect, afterEach } from "bun:test";
+import {
+  RestController,
+  GetMapping,
+  PostMapping,
+  Param,
+  Query,
+  metadataStorage,
+} from "@cinnabun/core";
+import { ApiTags, ApiOperation, ApiResponse } from "../src/index.js";
+import { scanRoutes } from "../src/generator/route-scanner.js";
+import { openApiMetadataStorage } from "../src/metadata/openapi-storage.js";
+
+afterEach(() => {
+  openApiMetadataStorage.reset();
+});
+
+describe("route-scanner", () => {
+  it("produces correct path entries from registered routes", () => {
+    @RestController("/api/openapi-users")
+    @ApiTags("Users")
+    class OpenApiRouteUserController {
+      @GetMapping("/")
+      @ApiOperation({ summary: "List users" })
+      @ApiResponse(200, { description: "List of users" })
+      findAll() {
+        return [];
+      }
+
+      @GetMapping("/:id")
+      @ApiOperation({ summary: "Get user by ID" })
+      findById(@Param("id") id: string) {
+        return { id };
+      }
+
+      @PostMapping("/")
+      create() {
+        return {};
+      }
+    }
+
+    const routes = scanRoutes();
+    const userRoutes = routes.filter(
+      (r) => r.controllerName === "OpenApiRouteUserController",
+    );
+
+    expect(userRoutes).toHaveLength(3);
+
+    const findAllRoute = userRoutes.find((r) => r.methodKey === "findAll");
+    expect(findAllRoute).toBeDefined();
+    expect(findAllRoute!.fullPath).toBe("/api/openapi-users");
+    expect(findAllRoute!.httpMethod).toBe("GET");
+    expect(findAllRoute!.tags).toEqual(["Users"]);
+    expect(findAllRoute!.operation?.summary).toBe("List users");
+    expect(findAllRoute!.responses).toHaveLength(1);
+    expect(findAllRoute!.responses[0].status).toBe(200);
+
+    const findByIdRoute = userRoutes.find((r) => r.methodKey === "findById");
+    expect(findByIdRoute).toBeDefined();
+    expect(findByIdRoute!.fullPath).toBe("/api/openapi-users/:id");
+    expect(findByIdRoute!.params).toHaveLength(1);
+    expect(findByIdRoute!.params[0].name).toBe("id");
+    expect(findByIdRoute!.params[0].source).toBe("param");
+
+    const createRoute = userRoutes.find((r) => r.methodKey === "create");
+    expect(createRoute).toBeDefined();
+    expect(createRoute!.httpMethod).toBe("POST");
+  });
+
+  it("excludes specified controllers from scan", () => {
+    @RestController("/api/openapi-exclude-users")
+    class OpenApiExcludeUserController {
+      @GetMapping("/")
+      findAll() {
+        return [];
+      }
+    }
+
+    @RestController("/internal")
+    class InternalController {
+      @GetMapping("/health")
+      health() {
+        return { ok: true };
+      }
+    }
+
+    const routesExcludingInternal = scanRoutes([InternalController]);
+    const hasInternal = routesExcludingInternal.some(
+      (r) => r.controllerName === "InternalController",
+    );
+    expect(hasInternal).toBe(false);
+
+    const hasUsers = routesExcludingInternal.some(
+      (r) => r.controllerName === "OpenApiExcludeUserController",
+    );
+    expect(hasUsers).toBe(true);
+  });
+
+  it("includes query params in scanned routes", () => {
+    @RestController("/search")
+    class SearchController {
+      @GetMapping("/")
+      search(@Query("q") q: string, @Query("limit") limit: string) {
+        return { q, limit };
+      }
+    }
+
+    const routes = scanRoutes();
+    const searchRoute = routes.find(
+      (r) => r.controllerName === "SearchController" && r.methodKey === "search",
+    );
+    expect(searchRoute).toBeDefined();
+    expect(searchRoute!.params).toHaveLength(2);
+    const queryParams = searchRoute!.params.filter((p) => p.source === "query");
+    expect(queryParams).toHaveLength(2);
+    expect(queryParams.map((p) => p.name)).toContain("q");
+    expect(queryParams.map((p) => p.name)).toContain("limit");
+  });
+});

package/__tests__/schema-converter.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import { convertZodSchema } from "../src/generator/schema-converter.js";
+
+describe("schema-converter", () => {
+  it("converts string schema to JSON Schema", () => {
+    const schema = z.string();
+    const { jsonSchema, componentName } = convertZodSchema(schema, "StringSchema");
+
+    expect(componentName).toBe("StringSchema");
+    expect(jsonSchema.type).toBe("string");
+    expect(jsonSchema.$schema).toBeUndefined();
+  });
+
+  it("converts number schema to JSON Schema", () => {
+    const schema = z.number();
+    const { jsonSchema } = convertZodSchema(schema, "NumberSchema");
+
+    expect(jsonSchema.type).toBe("number");
+  });
+
+  it("converts boolean schema to JSON Schema", () => {
+    const schema = z.boolean();
+    const { jsonSchema } = convertZodSchema(schema, "BoolSchema");
+
+    expect(jsonSchema.type).toBe("boolean");
+  });
+
+  it("converts object schema to JSON Schema", () => {
+    const schema = z.object({
+      name: z.string(),
+      age: z.number().optional(),
+      email: z.string().email(),
+    });
+    const { jsonSchema, componentName } = convertZodSchema(schema, "UserSchema");
+
+    expect(componentName).toBe("UserSchema");
+    expect(jsonSchema.type).toBe("object");
+    expect(jsonSchema.properties).toBeDefined();
+    expect(jsonSchema.properties).toHaveProperty("name");
+    expect(jsonSchema.properties).toHaveProperty("age");
+    expect(jsonSchema.properties).toHaveProperty("email");
+  });
+
+  it("converts array schema to JSON Schema", () => {
+    const schema = z.array(z.string());
+    const { jsonSchema } = convertZodSchema(schema, "StringArray");
+
+    expect(jsonSchema.type).toBe("array");
+    expect(jsonSchema.items).toBeDefined();
+  });
+
+  it("converts enum schema to JSON Schema", () => {
+    const schema = z.enum(["a", "b", "c"]);
+    const { jsonSchema } = convertZodSchema(schema, "StatusEnum");
+
+    expect(jsonSchema.enum).toEqual(["a", "b", "c"]);
+  });
+
+  it("removes $schema from output for OpenAPI compatibility", () => {
+    const schema = z.object({ foo: z.string() });
+    const { jsonSchema } = convertZodSchema(schema);
+
+    expect(jsonSchema.$schema).toBeUndefined();
+  });
+
+  it("uses default component name when not provided", () => {
+    const schema = z.string();
+    const { componentName } = convertZodSchema(schema);
+
+    expect(componentName).toBe("Schema");
+  });
+});

package/dist/decorators/api-operation.d.ts

@@ -0,0 +1,2 @@
+import { type ApiOperationMetadata } from "../metadata/openapi-storage.js";
+export declare function ApiOperation(metadata: ApiOperationMetadata): MethodDecorator;

package/dist/decorators/api-operation.js

@@ -0,0 +1,6 @@
+import { openApiMetadataStorage, } from "../metadata/openapi-storage.js";
+export function ApiOperation(metadata) {
+    return (target, propertyKey) => {
+        openApiMetadataStorage.setOperation(target.constructor, propertyKey, metadata);
+    };
+}

package/dist/decorators/api-property.d.ts

@@ -0,0 +1,2 @@
+import { type ApiPropertyMetadata } from "../metadata/openapi-storage.js";
+export declare function ApiProperty(metadata?: ApiPropertyMetadata): PropertyDecorator;

package/dist/decorators/api-property.js

@@ -0,0 +1,6 @@
+import { openApiMetadataStorage, } from "../metadata/openapi-storage.js";
+export function ApiProperty(metadata = {}) {
+    return (target, propertyKey) => {
+        openApiMetadataStorage.setProperty(target.constructor, propertyKey, metadata);
+    };
+}

package/dist/decorators/api-response.d.ts

@@ -0,0 +1,4 @@
+export declare function ApiResponse(status: number, metadata: {
+    description: string;
+    type?: any;
+}): MethodDecorator;

package/dist/decorators/api-response.js

@@ -0,0 +1,6 @@
+import { openApiMetadataStorage } from "../metadata/openapi-storage.js";
+export function ApiResponse(status, metadata) {
+    return (target, propertyKey) => {
+        openApiMetadataStorage.addResponse(target.constructor, propertyKey, { status, ...metadata });
+    };
+}

package/dist/decorators/api-tags.d.ts

@@ -0,0 +1 @@
+export declare function ApiTags(...tags: string[]): ClassDecorator;

package/dist/decorators/api-tags.js

@@ -0,0 +1,6 @@
+import { openApiMetadataStorage } from "../metadata/openapi-storage.js";
+export function ApiTags(...tags) {
+    return (target) => {
+        openApiMetadataStorage.setTags(target, tags);
+    };
+}

package/dist/generator/openapi-generator.d.ts

@@ -0,0 +1,25 @@
+import type { OpenApiModuleOptions } from "../interfaces/openapi-options.js";
+import type { ScannedRoute } from "./route-scanner.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 declare function generateSpec(options: OpenApiModuleOptions, routes: ScannedRoute[]): OpenApiSpec;