yaxa-svelte 2.1.0 → 2.3.0

package/dist/server/openapi/generator.js

@@ -0,0 +1,317 @@
+import { convertToJsonSchema } from './schema';
+import { globalApiRegistry } from './registry';
+/**
+ * Standard RFC 7807 Problem Details Schema for OpenAPI Components.
+ */
+const PROBLEM_DETAILS_SCHEMA = {
+    type: 'object',
+    properties: {
+        type: { type: 'string', format: 'uri', example: 'https://yaxa.dev/errors/validation-failed' },
+        title: { type: 'string', example: 'Unprocessable Entity' },
+        status: { type: 'integer', example: 422 },
+        detail: { type: 'string', example: 'Validation failed for 1 parameter(s).' },
+        instance: { type: 'string' },
+        invalidParams: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', example: 'body.email' },
+                    reason: { type: 'string', example: 'Invalid email address' }
+                },
+                required: ['name', 'reason']
+            }
+        }
+    },
+    required: ['type', 'title', 'status']
+};
+/**
+ * Extracts parameter list from a converted JSON schema.
+ */
+function extractParametersFromSchema(jsonSchema, location) {
+    if (!jsonSchema || typeof jsonSchema !== 'object' || !jsonSchema.properties) {
+        return [];
+    }
+    const requiredList = Array.isArray(jsonSchema.required) ? jsonSchema.required : [];
+    const parameters = [];
+    for (const [key, propSchema] of Object.entries(jsonSchema.properties)) {
+        parameters.push({
+            name: key,
+            in: location,
+            required: location === 'path' ? true : requiredList.includes(key),
+            description: propSchema?.description,
+            deprecated: propSchema?.deprecated,
+            schema: propSchema
+        });
+    }
+    return parameters;
+}
+/**
+ * Resolves YaxaEndpointConfig from an endpoint function or config object.
+ */
+function resolveConfig(endpoint) {
+    if (!endpoint)
+        return null;
+    if (typeof endpoint === 'function' && '_yaxaConfig' in endpoint) {
+        return endpoint._yaxaConfig;
+    }
+    if (typeof endpoint === 'object' && 'handle' in endpoint) {
+        return endpoint;
+    }
+    return null;
+}
+/**
+ * Generates an OpenAPI 3.1.0 document from registered yaxaEndpoints.
+ */
+export function generateOpenApiSpec(options = {}) {
+    const title = options.title || 'Yaxa SvelteKit API';
+    const version = options.version || '1.0.0';
+    const description = options.description || 'Auto-generated OpenAPI 3.1 contract via yaxa-svelte.';
+    const registry = options.registry || globalApiRegistry;
+    const registeredEndpoints = registry.getEndpoints();
+    // Merge manual options.endpoints if provided
+    const mergedEndpoints = {
+        ...registeredEndpoints
+    };
+    if (options.endpoints) {
+        for (const [rawPath, methods] of Object.entries(options.endpoints)) {
+            const normalizedPath = registry.normalizePath(rawPath);
+            if (!mergedEndpoints[normalizedPath]) {
+                mergedEndpoints[normalizedPath] = {};
+            }
+            for (const [method, handler] of Object.entries(methods)) {
+                mergedEndpoints[normalizedPath][method.toUpperCase()] = handler;
+            }
+        }
+    }
+    const paths = {};
+    const securitySchemes = {};
+    let usesSecurity = false;
+    for (const [path, methods] of Object.entries(mergedEndpoints)) {
+        paths[path] = {};
+        for (const [method, endpoint] of Object.entries(methods)) {
+            const config = resolveConfig(endpoint);
+            const methodLower = method.toLowerCase();
+            if (!config) {
+                // Fallback for raw RequestHandler
+                paths[path][methodLower] = {
+                    summary: `${method.toUpperCase()} ${path}`,
+                    responses: {
+                        '200': { description: 'Successful response' }
+                    }
+                };
+                continue;
+            }
+            const parameters = [];
+            // 1. Path Params
+            if (config.schema?.params) {
+                const paramsSchema = convertToJsonSchema(config.schema.params);
+                parameters.push(...extractParametersFromSchema(paramsSchema, 'path'));
+            }
+            else {
+                // Detect {param} placeholders in path and add basic string parameters
+                const pathParamMatches = path.match(/\{(\w+)\}/g);
+                if (pathParamMatches) {
+                    for (const match of pathParamMatches) {
+                        const paramName = match.slice(1, -1);
+                        parameters.push({
+                            name: paramName,
+                            in: 'path',
+                            required: true,
+                            schema: { type: 'string' }
+                        });
+                    }
+                }
+            }
+            // 2. Query Params
+            if (config.schema?.query) {
+                const querySchema = convertToJsonSchema(config.schema.query);
+                parameters.push(...extractParametersFromSchema(querySchema, 'query'));
+            }
+            // 3. Header Params
+            if (config.schema?.headers) {
+                const headersSchema = convertToJsonSchema(config.schema.headers);
+                parameters.push(...extractParametersFromSchema(headersSchema, 'header'));
+            }
+            // 4. Request Body
+            let requestBody = undefined;
+            if (config.schema?.body && method !== 'GET' && method !== 'HEAD') {
+                const bodySchema = convertToJsonSchema(config.schema.body);
+                requestBody = {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: bodySchema
+                        }
+                    }
+                };
+            }
+            // 5. Responses
+            const responses = {};
+            const successStatus = config.status
+                ? String(config.status)
+                : method === 'POST'
+                    ? '201'
+                    : '200';
+            if (config.responses) {
+                for (const [statusCode, resp] of Object.entries(config.responses)) {
+                    responses[String(statusCode)] = {
+                        description: resp.description,
+                        content: resp.schema
+                            ? {
+                                'application/json': {
+                                    schema: convertToJsonSchema(resp.schema)
+                                }
+                            }
+                            : undefined
+                    };
+                }
+            }
+            if (!responses[successStatus]) {
+                responses[successStatus] = {
+                    description: successStatus === '201'
+                        ? 'Created'
+                        : successStatus === '204'
+                            ? 'No Content'
+                            : 'Successful Operation',
+                    content: successStatus !== '204'
+                        ? {
+                            'application/json': {
+                                schema: { type: 'object' }
+                            }
+                        }
+                        : undefined
+                };
+            }
+            // 6. Guard Reflection (Security & Error Status Codes)
+            let hasAuthGuard = false;
+            let hasRoleGuard = false;
+            let roleGuardRoles = [];
+            let hasRateLimitGuard = false;
+            let rateLimitRetryAfter = 60;
+            if (config.guards && config.guards.length > 0) {
+                for (const guard of config.guards) {
+                    const meta = guard._yaxaGuard;
+                    if (meta) {
+                        if (meta.type === 'auth') {
+                            hasAuthGuard = true;
+                        }
+                        else if (meta.type === 'role') {
+                            hasRoleGuard = true;
+                            if (meta.roles)
+                                roleGuardRoles = meta.roles;
+                        }
+                        else if (meta.type === 'rateLimit') {
+                            hasRateLimitGuard = true;
+                            if (meta.options?.windowSeconds) {
+                                rateLimitRetryAfter = meta.options.windowSeconds;
+                            }
+                        }
+                    }
+                }
+            }
+            const operationSecurity = [];
+            if (hasAuthGuard || hasRoleGuard) {
+                usesSecurity = true;
+                securitySchemes['BearerAuth'] = {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT',
+                    description: 'Standard Bearer Token Header (`Authorization: Bearer <token>`)'
+                };
+                securitySchemes['CookieAuth'] = {
+                    type: 'apiKey',
+                    in: 'cookie',
+                    name: 'better-auth.session_token',
+                    description: 'Session cookie via Better-Auth'
+                };
+                operationSecurity.push({ BearerAuth: [] }, { CookieAuth: [] });
+                responses['401'] = {
+                    description: 'Unauthorized (RFC 7807 Problem Details)',
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            if (hasRoleGuard) {
+                responses['403'] = {
+                    description: `Forbidden — Insufficient role permissions. Requires: [${roleGuardRoles.join(', ')}]`,
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 7. Schema Validation Error (422)
+            if (config.schema &&
+                (config.schema.body || config.schema.query || config.schema.params || config.schema.headers)) {
+                responses['422'] = {
+                    description: 'Unprocessable Entity — Schema validation failed (RFC 7807)',
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 8. Rate Limit Error (429)
+            if (hasRateLimitGuard) {
+                responses['429'] = {
+                    description: 'Too Many Requests — Rate limit exceeded (RFC 7807)',
+                    headers: {
+                        'Retry-After': {
+                            description: 'Seconds to wait before retrying',
+                            schema: { type: 'integer', example: rateLimitRetryAfter }
+                        }
+                    },
+                    content: {
+                        'application/problem+json': {
+                            schema: { $ref: '#/components/schemas/ProblemDetails' }
+                        }
+                    }
+                };
+            }
+            // 9. Standard 500 Sanitized Error
+            responses['500'] = {
+                description: 'Internal Server Error — Sanitized exception (RFC 7807)',
+                content: {
+                    'application/problem+json': {
+                        schema: { $ref: '#/components/schemas/ProblemDetails' }
+                    }
+                }
+            };
+            const operation = {
+                summary: config.summary || `${method.toUpperCase()} ${path}`,
+                description: config.description,
+                operationId: config.operationId ||
+                    `${methodLower}_${path.replace(/[/{}]+/g, '_').replace(/^_+|_+$/g, '')}`,
+                tags: config.tags || (path.split('/')[2] ? [path.split('/')[2]] : ['Default']),
+                deprecated: config.deprecated,
+                parameters: parameters.length > 0 ? parameters : undefined,
+                requestBody,
+                responses,
+                security: operationSecurity.length > 0 ? operationSecurity : undefined
+            };
+            paths[path][methodLower] = operation;
+        }
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title,
+            version,
+            description
+        },
+        servers: options.servers || [{ url: '/', description: 'Current Environment' }],
+        paths,
+        components: {
+            schemas: {
+                ProblemDetails: PROBLEM_DETAILS_SCHEMA
+            },
+            securitySchemes: usesSecurity ? securitySchemes : undefined
+        }
+    };
+}

package/dist/server/openapi/handler.d.ts

@@ -0,0 +1,7 @@
+import type { RequestHandler } from '@sveltejs/kit';
+import type { ApiDocsOptions } from './types';
+/**
+ * Creates a turnkey SvelteKit RequestHandler that generates an interactive OpenAPI 3.1 documentation
+ * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
+ */
+export declare function createApiDocsHandler(options?: ApiDocsOptions): RequestHandler;

package/dist/server/openapi/handler.js

@@ -0,0 +1,117 @@
+import { generateOpenApiSpec } from './generator';
+function renderScalarHtml(specJson, title) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <style>
+      body { margin: 0; background-color: #0f172a; }
+    </style>
+  </head>
+  <body>
+    <script id="api-reference" data-configuration='{"darkMode":true,"layout":"modern"}' type="application/json">
+      ${specJson}
+    </script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`;
+}
+function renderSwaggerHtml(specJson, title) {
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
+    <style>
+      body { margin: 0; background: #fafafa; }
+    </style>
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+    <script>
+      window.ui = SwaggerUIBundle({
+        spec: ${specJson},
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIBundle.SwaggerUIStandalonePreset
+        ],
+        layout: "BaseLayout"
+      });
+    </script>
+  </body>
+</html>`;
+}
+function renderRedocHtml(specJson, title) {
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <style>
+      body { margin: 0; padding: 0; }
+    </style>
+  </head>
+  <body>
+    <div id="redoc-container"></div>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+    <script>
+      Redoc.init(${specJson}, {
+        scrollYOffset: 50,
+        theme: {
+          colors: { primary: { main: '#3b82f6' } }
+        }
+      }, document.getElementById('redoc-container'));
+    </script>
+  </body>
+</html>`;
+}
+/**
+ * Creates a turnkey SvelteKit RequestHandler that generates an interactive OpenAPI 3.1 documentation
+ * page (Scalar, Swagger UI, or Redoc) or returns raw OpenAPI 3.1 JSON when ?format=json is requested.
+ */
+export function createApiDocsHandler(options = {}) {
+    const theme = options.theme || 'scalar';
+    return async (event) => {
+        const { url, request } = event;
+        const format = url.searchParams.get('format');
+        const acceptHeader = request.headers.get('accept') || '';
+        const spec = generateOpenApiSpec(options);
+        // If caller requests JSON via query param, accept header, or path ending in .json
+        if (format === 'json' ||
+            acceptHeader.includes('application/json') ||
+            url.pathname.endsWith('/openapi.json')) {
+            return Response.json(spec, {
+                headers: {
+                    'content-type': 'application/json; charset=utf-8',
+                    'cache-control': 'public, max-age=60'
+                }
+            });
+        }
+        // Render Interactive HTML Docs
+        const specJson = JSON.stringify(spec);
+        let html;
+        if (theme === 'swagger') {
+            html = renderSwaggerHtml(specJson, spec.info.title);
+        }
+        else if (theme === 'redoc') {
+            html = renderRedocHtml(specJson, spec.info.title);
+        }
+        else {
+            html = renderScalarHtml(specJson, spec.info.title);
+        }
+        return new Response(html, {
+            headers: {
+                'content-type': 'text/html; charset=utf-8',
+                'cache-control': 'public, max-age=300'
+            }
+        });
+    };
+}

package/dist/server/openapi/index.d.ts

@@ -0,0 +1,5 @@
+export { generateOpenApiSpec } from './generator';
+export { createApiDocsHandler } from './handler';
+export { ApiRegistry, createApiRegistry, globalApiRegistry } from './registry';
+export { convertToJsonSchema } from './schema';
+export type { OpenApiSpec31, OpenApiOperation, OpenApiParameter, OpenApiRequestBody, OpenApiResponse, GenerateOpenApiOptions, ApiDocsOptions, ApiDocsTheme, EndpointLike, EndpointMap } from './types';

package/dist/server/openapi/index.js

@@ -0,0 +1,4 @@
+export { generateOpenApiSpec } from './generator';
+export { createApiDocsHandler } from './handler';
+export { ApiRegistry, createApiRegistry, globalApiRegistry } from './registry';
+export { convertToJsonSchema } from './schema';

package/dist/server/openapi/openapi.test.d.ts

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

package/dist/server/openapi/openapi.test.js

@@ -0,0 +1,219 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { z } from 'zod';
+import { createMockRequestEvent } from '../../testing/index.js';
+import { generateOpenApiSpec, createApiDocsHandler, createApiRegistry, globalApiRegistry, convertToJsonSchema } from './index.js';
+import { yaxaEndpoint } from '../endpoint/index.js';
+import { requireAuth, requireRole, rateLimit } from '../endpoint/guards.js';
+describe('OpenAPI 3.1 Schema Engine', () => {
+    it('converts Zod schema into compliant JSON Schema', () => {
+        const schema = z.object({
+            title: z.string().min(3),
+            count: z.number().optional(),
+            role: z.enum(['admin', 'member'])
+        });
+        const jsonSchema = convertToJsonSchema(schema);
+        expect(jsonSchema.type).toBe('object');
+        expect(jsonSchema.properties.title.type).toBe('string');
+        expect(jsonSchema.properties.count.type).toBe('number');
+        expect(jsonSchema.required).toContain('title');
+        expect(jsonSchema.required).toContain('role');
+        expect(jsonSchema.required).not.toContain('count');
+    });
+});
+describe('API Route Registry', () => {
+    let registry;
+    beforeEach(() => {
+        registry = createApiRegistry();
+        globalApiRegistry.clear();
+    });
+    it('normalizes SvelteKit bracket path params to OpenAPI curly braces', () => {
+        expect(registry.normalizePath('/api/items/[id]')).toBe('/api/items/{id}');
+        expect(registry.normalizePath('/api/orgs/[orgSlug]/users/[userId]')).toBe('/api/orgs/{orgSlug}/users/{userId}');
+        expect(registry.normalizePath('/api/files/[...rest]')).toBe('/api/files/{rest}');
+    });
+    it('registers endpoints and retrieves them in normalized form', () => {
+        const getHandler = yaxaEndpoint({ handle: () => [] });
+        registry.register('/api/users/[id]', { GET: getHandler });
+        const endpoints = registry.getEndpoints();
+        expect(endpoints['/api/users/{id}']).toBeDefined();
+        expect(endpoints['/api/users/{id}']['GET']).toBe(getHandler);
+    });
+});
+describe('generateOpenApiSpec Engine', () => {
+    const ItemParamsSchema = z.object({
+        id: z.string()
+    });
+    const ItemQuerySchema = z.object({
+        filter: z.string().optional(),
+        limit: z.number().optional()
+    });
+    const CreateItemBodySchema = z.object({
+        name: z.string().min(2),
+        price: z.number().positive()
+    });
+    it('generates complete OpenAPI 3.1 document with parameters, body and tags', () => {
+        const registry = createApiRegistry();
+        const getEndpoint = yaxaEndpoint({
+            summary: 'Get Item By ID',
+            description: 'Retrieves an item record by its unique ID',
+            tags: ['Items'],
+            schema: {
+                params: ItemParamsSchema,
+                query: ItemQuerySchema
+            },
+            handle: ({ params }) => ({ id: params.id })
+        });
+        const postEndpoint = yaxaEndpoint({
+            summary: 'Create Item',
+            tags: ['Items'],
+            schema: {
+                body: CreateItemBodySchema
+            },
+            handle: ({ body }) => body
+        });
+        registry.register('/api/items/[id]', { GET: getEndpoint });
+        registry.register('/api/items', { POST: postEndpoint });
+        const spec = generateOpenApiSpec({
+            title: 'Inventory API',
+            version: '2.0.0',
+            description: 'Test Inventory System',
+            registry
+        });
+        expect(spec.openapi).toBe('3.1.0');
+        expect(spec.info.title).toBe('Inventory API');
+        expect(spec.info.version).toBe('2.0.0');
+        // Verify GET /api/items/{id}
+        const getOp = spec.paths['/api/items/{id}']['get'];
+        expect(getOp.summary).toBe('Get Item By ID');
+        expect(getOp.tags).toEqual(['Items']);
+        expect(getOp.parameters).toHaveLength(3); // id (path), filter (query), limit (query)
+        const idParam = getOp.parameters?.find((p) => p.name === 'id');
+        expect(idParam?.in).toBe('path');
+        expect(idParam?.required).toBe(true);
+        // Verify POST /api/items
+        const postOp = spec.paths['/api/items']['post'];
+        expect(postOp.summary).toBe('Create Item');
+        expect(postOp.requestBody).toBeDefined();
+        expect(postOp.requestBody?.content['application/json'].schema?.type).toBe('object');
+        expect(postOp.responses['201']).toBeDefined();
+        expect(postOp.responses['422']).toBeDefined(); // Schema validation failed
+    });
+    it('deduces security schemes and RFC 7807 responses from guards automatically', () => {
+        const registry = createApiRegistry();
+        const secureEndpoint = yaxaEndpoint({
+            guards: [
+                requireAuth(),
+                requireRole(['admin', 'billing_manager']),
+                rateLimit({ points: 15, windowSeconds: 60 })
+            ],
+            schema: {
+                body: CreateItemBodySchema
+            },
+            handle: () => ({ ok: true })
+        });
+        registry.register('/api/secure-action', { POST: secureEndpoint });
+        const spec = generateOpenApiSpec({ registry });
+        const op = spec.paths['/api/secure-action']['post'];
+        // Security schemes attached
+        expect(spec.components?.securitySchemes?.BearerAuth).toBeDefined();
+        expect(spec.components?.securitySchemes?.CookieAuth).toBeDefined();
+        expect(op.security).toBeDefined();
+        // Guard error responses generated
+        expect(op.responses['401']).toBeDefined();
+        expect(op.responses['403']).toBeDefined();
+        expect(op.responses['403'].description).toContain('admin, billing_manager');
+        expect(op.responses['422']).toBeDefined();
+        expect(op.responses['429']).toBeDefined();
+        expect(op.responses['429'].headers?.['Retry-After']).toBeDefined();
+        expect(op.responses['500']).toBeDefined();
+        // Components schema ProblemDetails registered
+        expect(spec.components?.schemas?.ProblemDetails).toBeDefined();
+    });
+    it('supports self-registration via yaxaEndpoint path and method metadata', () => {
+        globalApiRegistry.clear();
+        yaxaEndpoint({
+            path: '/api/v1/auto-registered',
+            method: 'GET',
+            summary: 'Auto Registered Route',
+            handle: () => 'ok'
+        });
+        const spec = generateOpenApiSpec();
+        expect(spec.paths['/api/v1/auto-registered']?.['get']?.summary).toBe('Auto Registered Route');
+    });
+});
+describe('createApiDocsHandler Endpoint', () => {
+    it('serves OpenAPI 3.1 JSON when format=json query parameter is present', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Store API',
+            version: '1.2.3'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs?format=json'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('application/json');
+        const json = await response.json();
+        expect(json.openapi).toBe('3.1.0');
+        expect(json.info.title).toBe('Store API');
+        expect(json.info.version).toBe('1.2.3');
+    });
+    it('serves OpenAPI 3.1 JSON when Accept header requests application/json', async () => {
+        const handler = createApiDocsHandler();
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs',
+            headers: { accept: 'application/json' }
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('application/json');
+    });
+    it('renders Scalar HTML documentation by default', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Scalar Docs Test',
+            theme: 'scalar'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('text/html');
+        const html = await response.text();
+        expect(html).toContain('<title>Scalar Docs Test</title>');
+        expect(html).toContain('@scalar/api-reference');
+        expect(html).toContain('id="api-reference"');
+    });
+    it('renders Swagger UI HTML when theme is swagger', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Swagger Docs Test',
+            theme: 'swagger'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('text/html');
+        const html = await response.text();
+        expect(html).toContain('<title>Swagger Docs Test</title>');
+        expect(html).toContain('swagger-ui-dist');
+        expect(html).toContain('SwaggerUIBundle');
+    });
+    it('renders Redoc HTML when theme is redoc', async () => {
+        const handler = createApiDocsHandler({
+            title: 'Redoc Docs Test',
+            theme: 'redoc'
+        });
+        const event = createMockRequestEvent({
+            url: 'http://localhost:5173/api/docs'
+        });
+        const response = await handler(event);
+        expect(response.status).toBe(200);
+        expect(response.headers.get('content-type')).toContain('text/html');
+        const html = await response.text();
+        expect(html).toContain('<title>Redoc Docs Test</title>');
+        expect(html).toContain('redoc.standalone.js');
+        expect(html).toContain('redoc-container');
+    });
+});