@di-framework/di-framework-http 0.0.0-prerelease.308 → 0.0.0-prerelease.310

package/src/openapi.test.ts

@@ -1,36 +1,37 @@
-import { describe, it, expect } from "bun:test";
-import { generateOpenAPI } from "./openapi.ts";
+import { describe, it, expect } from 'bun:test';
+import { generateOpenAPI } from './openapi.ts';
+import { SCHEMAS } from './decorators.ts';
 
-describe("generateOpenAPI", () => {
-  it("should generate a default OpenAPI spec with default options", () => {
+describe('generateOpenAPI', () => {
+  it('should generate a default OpenAPI spec with default options', () => {
     const spec = generateOpenAPI({}, { getTargets: () => new Set() } as any);
 
-    expect(spec.openapi).toBe("3.1.0");
-    expect(spec.info.title).toBe("Generated API");
-    expect(spec.info.version).toBe("1.0.0");
+    expect(spec.openapi).toBe('3.1.0');
+    expect(spec.info.title).toBe('Generated API');
+    expect(spec.info.version).toBe('1.0.0');
     expect(spec.info.description).toBe(
-      "API documentation generated by @di-framework/di-framework-http.",
+      'API documentation generated by @di-framework/di-framework-http.',
     );
     expect(spec.paths).toEqual({});
     expect(spec.components.schemas).toEqual({});
   });
 
-  it("should use provided options in the OpenAPI spec", () => {
+  it('should use provided options in the OpenAPI spec', () => {
     const options = {
-      title: "Custom API",
-      version: "2.0.0",
-      description: "Custom description",
+      title: 'Custom API',
+      version: '2.0.0',
+      description: 'Custom description',
     };
     const spec = generateOpenAPI(options, {
       getTargets: () => new Set(),
     } as any);
 
-    expect(spec.info.title).toBe("Custom API");
-    expect(spec.info.version).toBe("2.0.0");
-    expect(spec.info.description).toBe("Custom description");
+    expect(spec.info.title).toBe('Custom API');
+    expect(spec.info.version).toBe('2.0.0');
+    expect(spec.info.description).toBe('Custom description');
   });
 
-  it("should correctly map a registry with controllers and endpoints", () => {
+  it('should correctly map a registry with controllers and endpoints', () => {
     // Mocking the structure that decorators create
     const mockController = class TestController {};
     // @ts-ignore
@@ -38,78 +39,78 @@ describe("generateOpenAPI", () => {
     // @ts-ignore
     mockController.post.isEndpoint = true;
     // @ts-ignore
-    mockController.post.path = "/test";
+    mockController.post.path = '/test';
     // @ts-ignore
-    mockController.post.method = "post";
+    mockController.post.method = 'post';
     // @ts-ignore
     mockController.post.metadata = {
-      summary: "Test Summary",
-      description: "Test Description",
-      requestBody: { content: { "application/json": {} } },
-      responses: { "201": { description: "Created" } },
+      summary: 'Test Summary',
+      description: 'Test Description',
+      requestBody: { content: { 'application/json': {} } },
+      responses: { '201': { description: 'Created' } },
     };
 
     const registry = { getTargets: () => new Set([mockController]) } as any;
     const spec = generateOpenAPI({}, registry);
 
-    expect(spec.paths["/test"]).toBeDefined();
-    expect(spec.paths["/test"].post).toBeDefined();
-    const operation = spec.paths["/test"].post;
-    expect(operation.summary).toBe("Test Summary");
-    expect(operation.description).toBe("Test Description");
-    expect(operation.operationId).toBe("TestController.post");
+    expect(spec.paths['/test']).toBeDefined();
+    expect(spec.paths['/test'].post).toBeDefined();
+    const operation = spec.paths['/test'].post;
+    expect(operation.summary).toBe('Test Summary');
+    expect(operation.description).toBe('Test Description');
+    expect(operation.operationId).toBe('TestController.post');
     expect(operation.requestBody).toBeDefined();
-    expect(operation.responses["201"]).toBeDefined();
+    expect(operation.responses['201']).toBeDefined();
   });
 
-  it("should handle endpoints without metadata", () => {
+  it('should handle endpoints without metadata', () => {
     const mockController = class SimpleController {};
     // @ts-ignore
     mockController.get = () => {};
     // @ts-ignore
     mockController.get.isEndpoint = true;
     // @ts-ignore
-    mockController.get.path = "/simple";
+    mockController.get.path = '/simple';
     // @ts-ignore
-    mockController.get.method = "get";
+    mockController.get.method = 'get';
 
     const registry = { getTargets: () => new Set([mockController]) } as any;
     const spec = generateOpenAPI({}, registry);
 
-    const operation = spec.paths["/simple"].get;
-    expect(operation.summary).toBe("get"); // defaults to property key
-    expect(operation.responses["200"]).toBeDefined(); // default response
-    expect(operation.responses["200"].description).toBe("OK");
+    const operation = spec.paths['/simple'].get;
+    expect(operation.summary).toBe('get'); // defaults to property key
+    expect(operation.responses['200']).toBeDefined(); // default response
+    expect(operation.responses['200'].description).toBe('OK');
   });
 
-  it("should handle multiple endpoints on the same path", () => {
+  it('should handle multiple endpoints on the same path', () => {
     const mockController = class MultiController {};
     // @ts-ignore
     mockController.get = () => {};
     // @ts-ignore
     mockController.get.isEndpoint = true;
     // @ts-ignore
-    mockController.get.path = "/resource";
+    mockController.get.path = '/resource';
     // @ts-ignore
-    mockController.get.method = "get";
+    mockController.get.method = 'get';
 
     // @ts-ignore
     mockController.post = () => {};
     // @ts-ignore
     mockController.post.isEndpoint = true;
     // @ts-ignore
-    mockController.post.path = "/resource";
+    mockController.post.path = '/resource';
     // @ts-ignore
-    mockController.post.method = "post";
+    mockController.post.method = 'post';
 
     const registry = { getTargets: () => new Set([mockController]) } as any;
     const spec = generateOpenAPI({}, registry);
 
-    expect(spec.paths["/resource"].get).toBeDefined();
-    expect(spec.paths["/resource"].post).toBeDefined();
+    expect(spec.paths['/resource'].get).toBeDefined();
+    expect(spec.paths['/resource'].post).toBeDefined();
   });
 
-  it("should handle unknown path and method defaults", () => {
+  it('should handle unknown path and method defaults', () => {
     const mockController = class WeirdController {};
     // @ts-ignore
     mockController.weird = () => {};
@@ -120,7 +121,89 @@ describe("generateOpenAPI", () => {
     const registry = { getTargets: () => new Set([mockController]) } as any;
     const spec = generateOpenAPI({}, registry);
 
-    expect(spec.paths["/unknown"]).toBeDefined();
-    expect(spec.paths["/unknown"].get).toBeDefined();
+    expect(spec.paths['/unknown']).toBeDefined();
+    expect(spec.paths['/unknown'].get).toBeDefined();
+  });
+
+  it('should convert :param paths to {param} and inject path parameters', () => {
+    const mockController = class ParamController {};
+    // @ts-ignore
+    mockController.getUser = () => {};
+    // @ts-ignore
+    mockController.getUser.isEndpoint = true;
+    // @ts-ignore
+    mockController.getUser.path = '/users/:userId/posts/:postId';
+    // @ts-ignore
+    mockController.getUser.method = 'get';
+
+    const registry = { getTargets: () => new Set([mockController]) } as any;
+    const spec = generateOpenAPI({}, registry);
+
+    const openApiPath = '/users/{userId}/posts/{postId}';
+    expect(spec.paths[openApiPath]).toBeDefined();
+    const operation = spec.paths[openApiPath].get;
+    expect(operation.parameters).toBeDefined();
+    expect(operation.parameters.length).toBe(2);
+    expect(operation.parameters[0]).toEqual({
+      name: 'userId',
+      in: 'path',
+      required: true,
+      schema: { type: 'string' },
+    });
+    expect(operation.parameters[1].name).toBe('postId');
+  });
+
+  it('should combine automatic path parameters with decorator parameters', () => {
+    const mockController = class MixController {};
+    // @ts-ignore
+    mockController.get = () => {};
+    // @ts-ignore
+    mockController.get.isEndpoint = true;
+    // @ts-ignore
+    mockController.get.path = '/items/:id';
+    // @ts-ignore
+    mockController.get.method = 'get';
+    // @ts-ignore
+    mockController.get.metadata = {
+      parameters: [{ name: 'filter', in: 'query' }],
+    };
+
+    const registry = { getTargets: () => new Set([mockController]) } as any;
+    const spec = generateOpenAPI({}, registry);
+
+    const operation = spec.paths['/items/{id}'].get;
+    expect(operation.parameters).toBeDefined();
+    expect(operation.parameters.length).toBe(2);
+    expect(operation.parameters[0].name).toBe('id');
+    expect(operation.parameters[0].in).toBe('path');
+    expect(operation.parameters[1].name).toBe('filter');
+    expect(operation.parameters[1].in).toBe('query');
+  });
+
+  it('should resolve referenced component schemas via the SCHEMAS symbol', () => {
+    const mockController = class SchemaController {};
+    // @ts-ignore
+    mockController[SCHEMAS] = new Set(['User', 'Post']);
+
+    const registry = { getTargets: () => new Set([mockController]) } as any;
+
+    // Provide the schema definitions in options
+    const schemas = {
+      User: {
+        type: 'object',
+        properties: { id: { type: 'string' }, profile: { $ref: '#/components/schemas/Profile' } },
+      },
+      Post: { type: 'object', properties: { title: { type: 'string' } } },
+      Profile: { type: 'object', properties: { age: { type: 'integer' } } }, // Transitive ref
+      Unused: { type: 'object' }, // Should not be included
+    };
+
+    const spec = generateOpenAPI({ schemas }, registry);
+
+    const resolved = spec.components.schemas;
+    expect(resolved['User']).toBeDefined();
+    expect(resolved['Post']).toBeDefined();
+    expect(resolved['Profile']).toBeDefined(); // Transitively resolved!
+    expect(resolved['Unused']).toBeUndefined();
   });
 });

package/src/openapi.ts

@@ -1,24 +1,81 @@
-import registry from "./registry.ts";
+import registry from './registry.ts';
+import { SCHEMAS } from './decorators.ts';
 
 export type OpenAPIOptions = {
   title?: string;
   version?: string;
   description?: string;
   outputPath?: string;
+  schemas?: Record<string, unknown>;
 };
 
-export function generateOpenAPI(
-  options: OpenAPIOptions = {},
-  registryToUse = registry,
-) {
+/** Recursively extract `$ref` schema names from a value. */
+function collectRefs(obj: unknown, out: Set<string>): void {
+  if (typeof obj !== 'object' || obj === null) return;
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) collectRefs(item, out);
+    return;
+  }
+
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    if (key === '$ref' && typeof value === 'string') {
+      const match = /^#\/components\/schemas\/(.+)$/.exec(value);
+      if (match?.[1]) out.add(match[1]);
+    } else {
+      collectRefs(value, out);
+    }
+  }
+}
+
+/**
+ * Resolve a schema name and all schemas it transitively references.
+ * Writes resolved schemas into `resolved`.
+ */
+function resolveSchema(
+  name: string,
+  resolved: Record<string, unknown>,
+  schemas: Record<string, unknown>,
+): void {
+  if (name in resolved) return;
+
+  const schema = schemas[name];
+  if (!schema) return;
+
+  resolved[name] = schema;
+
+  // Find transitive refs within the schema itself
+  const transitive = new Set<string>();
+  collectRefs(schema, transitive);
+  for (const dep of transitive) {
+    resolveSchema(dep, resolved, schemas);
+  }
+}
+
+/** Convert itty-router `:param` paths to OpenAPI `{param}` format. */
+function toOpenAPIPath(path: string): string {
+  return path.replace(/:([a-zA-Z_]\w*)/g, '{$1}');
+}
+
+/** Extract path parameter names from an itty-router path. */
+function extractPathParams(path: string): string[] {
+  const names: string[] = [];
+  const re = /:([a-zA-Z_]\w*)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(path)) !== null) {
+    if (m[1]) names.push(m[1]);
+  }
+  return names;
+}
+
+export function generateOpenAPI(options: OpenAPIOptions = {}, registryToUse = registry) {
   const spec: any = {
-    openapi: "3.1.0",
+    openapi: '3.1.0',
     info: {
-      title: options.title || "Generated API",
-      version: options.version || "1.0.0",
+      title: options.title || 'Generated API',
+      version: options.version || '1.0.0',
       description:
-        options.description ||
-        "API documentation generated by @di-framework/di-framework-http.",
+        options.description || 'API documentation generated by @di-framework/di-framework-http.',
     },
     paths: {},
     components: {
@@ -28,13 +85,19 @@ export function generateOpenAPI(
 
   const targets = registryToUse.getTargets();
 
+  const metaParamsMap = new Map<string, unknown[]>();
+
   for (const target of targets) {
     // Look for endpoints on the target (static properties)
     for (const key of Object.getOwnPropertyNames(target)) {
-      const property = target[key];
+      const property = (target as any)[key];
       if (property && property.isEndpoint) {
-        const path = property.path || "/unknown";
-        const method = property.method || "get";
+        const path = property.path || '/unknown';
+        const method = (property.method || 'get').toLowerCase();
+
+        if (property.metadata?.parameters) {
+          metaParamsMap.set(`${path}|${method}`, property.metadata.parameters as unknown[]);
+        }
 
         if (!spec.paths[path]) {
           spec.paths[path] = {};
@@ -46,8 +109,8 @@ export function generateOpenAPI(
           operationId: `${target.name}.${key}`,
           requestBody: property.metadata?.requestBody,
           responses: property.metadata?.responses || {
-            "200": {
-              description: "OK",
+            '200': {
+              description: 'OK',
             },
           },
         };
@@ -55,5 +118,46 @@ export function generateOpenAPI(
     }
   }
 
+  // Rewrite paths: convert :param → {param} and inject parameters
+  const rewrittenPaths: Record<string, Record<string, unknown>> = {};
+
+  for (const [rawPath, methods] of Object.entries(spec.paths)) {
+    const openApiPath = toOpenAPIPath(rawPath);
+    const pathParamNames = extractPathParams(rawPath);
+
+    const autoParams = pathParamNames.map((name) => ({
+      name,
+      in: 'path',
+      required: true,
+      schema: { type: 'string' },
+    }));
+
+    rewrittenPaths[openApiPath] ??= {};
+
+    for (const [method, operation] of Object.entries(methods as Record<string, any>)) {
+      const decoratorParams = metaParamsMap.get(`${rawPath}|${method}`) ?? [];
+      if (autoParams.length > 0 || decoratorParams.length > 0) {
+        operation.parameters = [...autoParams, ...decoratorParams];
+      }
+      rewrittenPaths[openApiPath][method] = operation;
+    }
+  }
+
+  spec.paths = rewrittenPaths;
+
+  // Collect schemas from decorator Symbols
+  const resolved: Record<string, unknown> = {};
+
+  for (const target of targets) {
+    const refs: Set<string> | undefined = (target as Record<symbol, Set<string>>)[SCHEMAS];
+    if (!refs) continue;
+
+    for (const name of refs) {
+      resolveSchema(name, resolved, options.schemas || {});
+    }
+  }
+
+  spec.components.schemas = resolved;
+
   return spec;
 }

package/src/registry.ts

@@ -26,7 +26,7 @@ export class Registry {
   }
 }
 
-const GLOBAL_KEY = Symbol.for("@di-framework/http-registry");
+const GLOBAL_KEY = Symbol.for('@di-framework/http-registry');
 
 const registry: Registry =
   (globalThis as any)[GLOBAL_KEY] ?? ((globalThis as any)[GLOBAL_KEY] = new Registry());