codehooks-js 1.3.25 → 1.4.0

package/openapi/generator.mjs

@@ -0,0 +1,417 @@
+/**
+ * OpenAPI specification generator
+ * Generates OpenAPI 3.0.3 spec from Codehooks routes and metadata
+ */
+
+import { generateCrudlifyPaths } from './crudlify-docs.mjs';
+import { convertToJsonSchema, detectSchemaType } from './schema-converter.mjs';
+
+const DEFAULT_SPEC = {
+  openapi: '3.0.3',
+  info: {
+    title: 'Codehooks API',
+    version: '1.0.0'
+  },
+  servers: [],
+  paths: {},
+  components: {
+    schemas: {},
+    securitySchemes: {
+      apiKey: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'x-apikey',
+        description: 'Codehooks API key for authentication'
+      },
+      bearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+        description: 'JWT Bearer token authentication'
+      }
+    }
+  },
+  tags: []
+};
+
+/**
+ * Generate complete OpenAPI specification
+ * @param {object} app - Codehooks app instance
+ * @param {object} config - OpenAPI configuration
+ * @returns {Promise<object>} OpenAPI specification
+ */
+export async function generateOpenApiSpec(app, config = {}) {
+  const spec = {
+    openapi: '3.0.3',
+    info: {
+      ...DEFAULT_SPEC.info,
+      ...config.info
+    },
+    servers: config.servers || [],
+    paths: {},
+    components: {
+      schemas: {},
+      securitySchemes: {
+        ...DEFAULT_SPEC.components.securitySchemes
+      }
+    },
+    // Default security - require API key for all endpoints
+    security: [{ apiKey: [] }]
+  };
+
+  // Add tags if provided
+  if (config.tags && config.tags.length > 0) {
+    spec.tags = config.tags;
+  }
+
+  // 2. Get crudlify config (needed to filter generic routes)
+  const crudlifySchema = app.settings['_crudlify_schema'];
+  const crudlifyOptions = app.settings['_crudlify_options'] || {};
+  const crudlifyEnabled = crudlifySchema !== undefined;
+
+  // 1. Generate paths from custom routes with openapi() metadata
+  // Pass crudlify info to filter out generic /:collection routes
+  const { paths: customPaths, schemas: customSchemas } = await generateCustomRoutePaths(
+    app.routes,
+    app.openApiMeta || {},
+    crudlifyEnabled ? crudlifyOptions.prefix || '' : null
+  );
+  let crudlifyPaths = {};
+  let crudlifyComponents = { schemas: {} };
+
+  // Generate crudlify docs if enabled (even with no schemas - will show generic docs)
+  if (crudlifyEnabled) {
+    try {
+      const crudDocs = await generateCrudlifyPaths(crudlifySchema || {}, crudlifyOptions);
+      crudlifyPaths = crudDocs.paths;
+      crudlifyComponents = crudDocs.components;
+    } catch (error) {
+      console.warn('Failed to generate crudlify docs:', error.message);
+    }
+  }
+
+  // 3. Merge paths (custom routes take precedence over crudlify)
+  let mergedPaths = mergePaths(crudlifyPaths, customPaths);
+
+  // 4. Apply filter if provided
+  if (typeof config.filter === 'function') {
+    mergedPaths = filterPaths(mergedPaths, config.filter);
+  }
+
+  spec.paths = mergedPaths;
+
+  // 5. Merge component schemas (custom routes + crudlify + user config)
+  spec.components.schemas = {
+    ...crudlifyComponents.schemas,
+    ...customSchemas,
+    ...(config.components?.schemas || {})
+  };
+
+  // 6. Merge security schemes (user config + defaults)
+  if (config.components?.securitySchemes) {
+    spec.components.securitySchemes = {
+      ...spec.components.securitySchemes,
+      ...config.components.securitySchemes
+    };
+  }
+
+  // 7. Add global security if configured
+  if (config.security) {
+    spec.security = config.security;
+  }
+
+  // 8. Add external docs if configured
+  if (config.externalDocs) {
+    spec.externalDocs = config.externalDocs;
+  }
+
+  return spec;
+}
+
+/**
+ * Generate OpenAPI paths from custom routes
+ * @param {object} routes - App routes object
+ * @param {object} openApiMeta - Route metadata from openapi() wrappers
+ * @param {string|null} crudlifyPrefix - Crudlify prefix if enabled, null if disabled
+ * @returns {Promise<{paths: object, schemas: object}>} OpenAPI paths and schemas
+ */
+async function generateCustomRoutePaths(routes, openApiMeta, crudlifyPrefix) {
+  const paths = {};
+  const schemas = {};
+
+  for (const [routeKey, handlers] of Object.entries(routes)) {
+    // Parse "METHOD /path" format
+    const spaceIndex = routeKey.indexOf(' ');
+    if (spaceIndex === -1) continue;
+
+    const method = routeKey.substring(0, spaceIndex);
+    const path = routeKey.substring(spaceIndex + 1);
+
+    // Skip regex routes (too complex to document automatically)
+    if (path.startsWith('{')) {
+      continue;
+    }
+
+    // Skip internal routes (OpenAPI spec and docs routes)
+    if (path.includes('openapi.json') || path.includes('/docs')) {
+      continue;
+    }
+
+    // Skip crudlify generic routes (they use :collection parameter)
+    // These are documented via crudlify-docs.mjs with specific collection names
+    if (crudlifyPrefix !== null && isCrudlifyGenericRoute(path, crudlifyPrefix)) {
+      continue;
+    }
+
+    // Convert Express-style params to OpenAPI style: :id -> {id}
+    const openApiPath = convertPathParams(path);
+
+    if (!paths[openApiPath]) {
+      paths[openApiPath] = {};
+    }
+
+    // Get metadata from openapi() wrapper or generate default
+    const meta = openApiMeta[routeKey] || {};
+    const httpMethod = method === '*' ? 'get' : method.toLowerCase();
+
+    // Don't overwrite if method already exists (from crudlify)
+    if (paths[openApiPath][httpMethod]) {
+      // Merge metadata if there's custom metadata
+      if (Object.keys(meta).length > 0) {
+        paths[openApiPath][httpMethod] = {
+          ...paths[openApiPath][httpMethod],
+          ...meta
+        };
+      }
+      continue;
+    }
+
+    // Build operation object
+    const operation = {
+      summary: meta.summary || `${method} ${path}`,
+      tags: meta.tags || ['default'],
+      parameters: meta.parameters || extractPathParams(path),
+      responses: meta.responses || { 200: { description: 'Success' } }
+    };
+
+    // Add optional fields
+    if (meta.description) {
+      operation.description = meta.description;
+    }
+    if (meta.operationId) {
+      operation.operationId = meta.operationId;
+    }
+    if (meta.requestBody) {
+      // Process request body and extract schema for components
+      const { processedBody, schemaName, schema } = await processRequestBodyWithSchema(
+        meta.requestBody,
+        meta.schemaName || meta.operationId || deriveSchemaName(path, method)
+      );
+      operation.requestBody = processedBody;
+
+      // Register schema in components if we extracted one
+      if (schemaName && schema) {
+        schemas[schemaName] = schema;
+      }
+    }
+    if (meta.security) {
+      operation.security = meta.security;
+    }
+    if (meta.deprecated) {
+      operation.deprecated = true;
+    }
+
+    paths[openApiPath][httpMethod] = operation;
+  }
+
+  return { paths, schemas };
+}
+
+/**
+ * Derive a schema name from path and method
+ * @param {string} path - Route path
+ * @param {string} method - HTTP method
+ * @returns {string} Schema name
+ */
+function deriveSchemaName(path, method) {
+  // Convert /orders/:id to OrdersId, POST /orders to CreateOrder
+  const parts = path.split('/').filter(p => p && !p.startsWith(':'));
+  const baseName = parts.map(p => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+
+  const prefixes = {
+    'POST': 'Create',
+    'PUT': 'Update',
+    'PATCH': 'Patch',
+    'GET': '',
+    'DELETE': 'Delete'
+  };
+
+  const prefix = prefixes[method.toUpperCase()] || '';
+  return `${prefix}${baseName}Request`;
+}
+
+/**
+ * Process request body, converting schemas and extracting for components
+ * @param {object} requestBody - Request body spec
+ * @param {string} schemaName - Name to use for the schema in components
+ * @returns {Promise<{processedBody: object, schemaName: string|null, schema: object|null}>}
+ */
+async function processRequestBodyWithSchema(requestBody, schemaName) {
+  const result = {
+    ...requestBody,
+    content: {}
+  };
+
+  let extractedSchema = null;
+  let extractedSchemaName = null;
+
+  if (requestBody.content) {
+    for (const [contentType, contentSpec] of Object.entries(requestBody.content)) {
+      result.content[contentType] = { ...contentSpec };
+
+      const schema = contentSpec.schema;
+      if (schema) {
+        const schemaType = detectSchemaType(schema);
+        // If it's a Zod or Yup schema, convert it
+        if (schemaType === 'zod' || schemaType === 'yup') {
+          try {
+            const convertedSchema = await convertToJsonSchema(schema);
+            // Store schema in components and use $ref
+            extractedSchema = convertedSchema;
+            extractedSchemaName = schemaName;
+            result.content[contentType].schema = { $ref: `#/components/schemas/${schemaName}` };
+          } catch (error) {
+            // Fall back to generic object
+            result.content[contentType].schema = { type: 'object' };
+          }
+        }
+        // Otherwise keep the schema as-is (already JSON Schema or $ref)
+      }
+    }
+  }
+
+  return {
+    processedBody: result,
+    schemaName: extractedSchemaName,
+    schema: extractedSchema
+  };
+}
+
+/**
+ * Convert Express-style path params to OpenAPI style
+ * /users/:id -> /users/{id}
+ * @param {string} path - Express-style path
+ * @returns {string} OpenAPI-style path
+ */
+function convertPathParams(path) {
+  return path.replace(/:(\w+)/g, '{$1}');
+}
+
+/**
+ * Extract path parameters from Express-style path
+ * @param {string} path - Express-style path
+ * @returns {Array} OpenAPI parameters array
+ */
+function extractPathParams(path) {
+  const params = [];
+  const regex = /:(\w+)/g;
+  let match;
+
+  while ((match = regex.exec(path)) !== null) {
+    params.push({
+      name: match[1],
+      in: 'path',
+      required: true,
+      schema: { type: 'string' }
+    });
+  }
+
+  return params;
+}
+
+/**
+ * Merge paths objects, with later objects taking precedence
+ * @param  {...object} pathsObjects - Multiple paths objects
+ * @returns {object} Merged paths
+ */
+function mergePaths(...pathsObjects) {
+  const merged = {};
+
+  for (const paths of pathsObjects) {
+    for (const [path, methods] of Object.entries(paths)) {
+      if (!merged[path]) {
+        merged[path] = {};
+      }
+      for (const [method, operation] of Object.entries(methods)) {
+        merged[path][method] = operation;
+      }
+    }
+  }
+
+  // Sort paths alphabetically for consistent output
+  const sorted = {};
+  const sortedKeys = Object.keys(merged).sort();
+  for (const key of sortedKeys) {
+    sorted[key] = merged[key];
+  }
+
+  return sorted;
+}
+
+/**
+ * Filter paths using a user-provided filter function
+ * @param {object} paths - OpenAPI paths object
+ * @param {function} filterFn - Filter function: (op) => boolean
+ *   op: { method: string, path: string, operation: object }
+ *   Returns true to include, false to exclude
+ * @returns {object} Filtered paths
+ */
+function filterPaths(paths, filterFn) {
+  const filtered = {};
+
+  for (const [path, methods] of Object.entries(paths)) {
+    const filteredMethods = {};
+
+    for (const [method, operation] of Object.entries(methods)) {
+      const op = {
+        method,
+        path,
+        operationId: operation.operationId,
+        tags: operation.tags || [],
+        summary: operation.summary
+      };
+
+      if (filterFn(op)) {
+        filteredMethods[method] = operation;
+      }
+    }
+
+    // Only include path if it has at least one method
+    if (Object.keys(filteredMethods).length > 0) {
+      filtered[path] = filteredMethods;
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Check if a path is a crudlify generic route
+ * Crudlify registers routes like /:collection, /:collection/:ID, /:collection/_byquery
+ * @param {string} path - Route path
+ * @param {string} prefix - Crudlify prefix
+ * @returns {boolean} True if this is a crudlify generic route
+ */
+function isCrudlifyGenericRoute(path, prefix) {
+  // Normalize prefix
+  const normalizedPrefix = prefix || '';
+
+  // Crudlify route patterns (with optional prefix)
+  const crudlifyPatterns = [
+    `${normalizedPrefix}/:collection`,
+    `${normalizedPrefix}/:collection/:ID`,
+    `${normalizedPrefix}/:collection/_byquery`
+  ];
+
+  return crudlifyPatterns.includes(path);
+}

package/openapi/index.mjs

@@ -0,0 +1,221 @@
+/**
+ * OpenAPI documentation module for Codehooks
+ *
+ * @example
+ * import { app, openapi } from 'codehooks-js';
+ *
+ * // Enable OpenAPI docs
+ * app.openapi({ info: { title: 'My API', version: '1.0.0' } }, '/docs');
+ *
+ * // Document a custom route
+ * app.get('/health',
+ *   openapi({
+ *     summary: 'Health check',
+ *     tags: ['System'],
+ *     responses: { 200: { description: 'OK' } }
+ *   }),
+ *   (req, res) => res.json({ status: 'ok' })
+ * );
+ */
+
+export { generateOpenApiSpec } from './generator.mjs';
+export { generateSwaggerHtml } from './swagger-ui.mjs';
+export { convertToJsonSchema, detectSchemaType } from './schema-converter.mjs';
+export { generateCrudlifyPaths } from './crudlify-docs.mjs';
+
+/**
+ * Create an OpenAPI documentation wrapper middleware
+ *
+ * This middleware attaches OpenAPI metadata to the route, which is then
+ * extracted during route registration and used for spec generation.
+ *
+ * @param {object} spec - OpenAPI operation specification
+ * @param {string} [spec.summary] - Short summary of the operation
+ * @param {string} [spec.description] - Detailed description
+ * @param {string[]} [spec.tags] - Tags for grouping in docs
+ * @param {string} [spec.operationId] - Unique operation identifier
+ * @param {Array} [spec.parameters] - Path, query, header, cookie parameters
+ * @param {object} [spec.requestBody] - Request body specification
+ * @param {object} [spec.responses] - Response specifications by status code
+ * @param {Array} [spec.security] - Security requirements
+ * @param {boolean} [spec.deprecated] - Whether operation is deprecated
+ * @returns {Function} Middleware function with attached metadata
+ *
+ * @example
+ * app.post('/users',
+ *   openapi({
+ *     summary: 'Create a new user',
+ *     tags: ['Users'],
+ *     requestBody: {
+ *       required: true,
+ *       content: {
+ *         'application/json': {
+ *           schema: {
+ *             type: 'object',
+ *             required: ['name', 'email'],
+ *             properties: {
+ *               name: { type: 'string' },
+ *               email: { type: 'string', format: 'email' }
+ *             }
+ *           }
+ *         }
+ *       }
+ *     },
+ *     responses: {
+ *       201: { description: 'User created' },
+ *       400: { description: 'Validation error' }
+ *     }
+ *   }),
+ *   async (req, res) => {
+ *     // Handle user creation
+ *   }
+ * );
+ */
+export function openapi(spec) {
+  // Create a pass-through middleware
+  const wrapper = function openapiMiddleware(req, res, next) {
+    // Simply continue to the next handler
+    if (typeof next === 'function') {
+      next();
+    }
+  };
+
+  // Attach the OpenAPI spec to the function for later extraction
+  wrapper._openApiSpec = spec;
+
+  // Mark as openapi middleware for easy detection
+  wrapper._isOpenApiMiddleware = true;
+
+  return wrapper;
+}
+
+/**
+ * Helper to create response specification
+ * @param {string} description - Response description
+ * @param {object} [schema] - Response schema (JSON Schema or Zod/Yup)
+ * @param {string} [contentType='application/json'] - Content type
+ * @returns {object} OpenAPI response object
+ *
+ * @example
+ * openapi({
+ *   responses: {
+ *     200: response('Success', UserSchema),
+ *     404: response('Not found')
+ *   }
+ * })
+ */
+export function response(description, schema, contentType = 'application/json') {
+  if (!schema) {
+    return { description };
+  }
+
+  return {
+    description,
+    content: {
+      [contentType]: { schema }
+    }
+  };
+}
+
+/**
+ * Helper to create request body specification
+ * @param {object} schema - Request body schema (JSON Schema or Zod/Yup)
+ * @param {object} [options] - Additional options
+ * @param {boolean} [options.required=true] - Whether body is required
+ * @param {string} [options.description] - Body description
+ * @param {string} [options.contentType='application/json'] - Content type
+ * @returns {object} OpenAPI request body object
+ *
+ * @example
+ * openapi({
+ *   requestBody: body(CreateUserSchema, { description: 'User data' })
+ * })
+ */
+export function body(schema, options = {}) {
+  const {
+    required = true,
+    description,
+    contentType = 'application/json'
+  } = options;
+
+  return {
+    required,
+    ...(description && { description }),
+    content: {
+      [contentType]: { schema }
+    }
+  };
+}
+
+/**
+ * Helper to create path parameter specification
+ * @param {string} name - Parameter name
+ * @param {object} [options] - Parameter options
+ * @param {string} [options.description] - Parameter description
+ * @param {object} [options.schema] - Parameter schema
+ * @param {*} [options.example] - Example value
+ * @returns {object} OpenAPI parameter object
+ *
+ * @example
+ * openapi({
+ *   parameters: [
+ *     param('id', { description: 'User ID', schema: { type: 'string', format: 'uuid' } })
+ *   ]
+ * })
+ */
+export function param(name, options = {}) {
+  return {
+    name,
+    in: 'path',
+    required: true,
+    schema: options.schema || { type: 'string' },
+    ...(options.description && { description: options.description }),
+    ...(options.example !== undefined && { example: options.example })
+  };
+}
+
+/**
+ * Helper to create query parameter specification
+ * @param {string} name - Parameter name
+ * @param {object} [options] - Parameter options
+ * @param {string} [options.description] - Parameter description
+ * @param {boolean} [options.required=false] - Whether required
+ * @param {object} [options.schema] - Parameter schema
+ * @param {*} [options.example] - Example value
+ * @returns {object} OpenAPI parameter object
+ *
+ * @example
+ * openapi({
+ *   parameters: [
+ *     query('limit', { description: 'Max items', schema: { type: 'integer', default: 10 } }),
+ *     query('search', { description: 'Search term' })
+ *   ]
+ * })
+ */
+export function query(name, options = {}) {
+  return {
+    name,
+    in: 'query',
+    required: options.required || false,
+    schema: options.schema || { type: 'string' },
+    ...(options.description && { description: options.description }),
+    ...(options.example !== undefined && { example: options.example })
+  };
+}
+
+/**
+ * Helper to create header parameter specification
+ * @param {string} name - Header name
+ * @param {object} [options] - Parameter options
+ * @returns {object} OpenAPI parameter object
+ */
+export function header(name, options = {}) {
+  return {
+    name,
+    in: 'header',
+    required: options.required || false,
+    schema: options.schema || { type: 'string' },
+    ...(options.description && { description: options.description }),
+    ...(options.example !== undefined && { example: options.example })
+  };
+}