codehooks-js 1.3.25 → 1.4.1

package/README.md

@@ -128,6 +128,33 @@ app.crudlify();
 export default app.init();
 ```
 
+## OpenAPI Documentation
+
+Automatically generate interactive API documentation with Swagger UI:
+
+```javascript
+import { app } from 'codehooks-js';
+import { z } from 'zod';
+
+const userSchema = z.object({
+  name: z.string().min(1).describe('User name'),
+  email: z.string().email().describe('Email address'),
+  role: z.enum(['admin', 'user']).default('user')
+});
+
+app.openapi({
+  info: { title: 'My API', version: '1.0.0' }
+});
+
+app.crudlify({ users: userSchema });
+
+export default app.init();
+```
+
+After deploying, visit `/docs` for Swagger UI or `/openapi.json` for the spec.
+
+Supports **Zod**, **Yup**, and **JSON Schema** for validation and documentation. See [OpenAPI Documentation](https://codehooks.io/docs/openapi-swagger-docs) for details.
+
 ## Compile
 
 When running the `coho compile` command, it will automatically create a `tsconfig.json` file in the project directory. The tsconfig file can be further adapted to your needs, the initial configuration is shown in the example below:
@@ -212,6 +239,7 @@ The Codehooks class provides a comprehensive backend application framework with
 - **`set(key, val)`** - Set application configuration settings
 - **`render(view, data, cb)`** - Render templates with data
 - **`crudlify(schema, options)`** - Auto-generate CRUD REST API endpoints
+- **`openapi(config, uiPath)`** - Enable OpenAPI/Swagger documentation at `/docs` and `/openapi.json`
 
 ### **Real-time Communication APIs**
 

package/crudlify/index.mjs

@@ -20,6 +20,10 @@ export default async function crudlify(app, schema = {}, options = { schema: "yu
     if (_opt.prefix === undefined || _opt.prefix === '/') {
         _opt.prefix = '';
     }
+
+    // Store schema info for OpenAPI documentation
+    app.set('_crudlify_schema', schema);
+    app.set('_crudlify_options', _opt);
  
     try {
         // the DB variable is present when running as a codehooks.io app

package/crudlify/lib/schema/json-schema/index.mjs

@@ -1,41 +1,57 @@
-//z-schema method
-let validator = null;
+// JSON Schema validation using ajv (available in Codehooks runtime)
+import Ajv from 'ajv';
+
+let ajv = null;
+let compiledSchemas = {};
 const debug = console.debug;
 
 /**
- * 
- * @param {*} schema 
- * @param {*} document 
- * @returns 
+ * Validate a document against a JSON Schema
+ * @param {*} schema
+ * @param {*} document
+ * @param {*} options
+ * @returns
  */
 export const validate = (schema, document, options) => {
     debug('Validate JSON-schema', document, schema)
     return new Promise((resolve, reject) => {
-        const valid = options.validator.validate(document, schema);
+        if (!ajv) {
+            reject(new Error('No JSON Schema validator available'));
+            return;
+        }
+
+        // Get or compile the validator for this schema
+        const schemaKey = JSON.stringify(schema);
+        let validateFn = compiledSchemas[schemaKey];
+        if (!validateFn) {
+            try {
+                validateFn = ajv.compile(schema);
+                compiledSchemas[schemaKey] = validateFn;
+            } catch (e) {
+                reject(new Error(`Invalid JSON Schema: ${e.message}`));
+                return;
+            }
+        }
+
+        const valid = validateFn(document);
         debug('isValid', valid)
         if (!valid) {
-            reject(options.validator.getLastErrors());
+            reject(validateFn.errors);
         } else {
             resolve(document);
         }
     })
 }
 
-/*
-var validator = new ZSchema();
-
-
-// now validate our data against the last schema
-var valid = validator.validate(data, schemas[2]);
-*/
-
 export const cast = (schema, document) => {
     debug('Cast', document, schema)
     return document;
 }
 
 export const prepare = (schemas, options) => {
-    validator = options.validator;
-    debug('Json-schema prep', options)
-    return schemas;   
+    // Use provided ajv instance or create default
+    ajv = options?.validator || new Ajv({ allErrors: true, strict: false });
+    compiledSchemas = {};
+    debug('Json-schema prep, using ajv')
+    return schemas;
 }

package/index.js

@@ -2,6 +2,8 @@ import {agg} from './aggregation/index.mjs';
 import {crudlify as crud} from './crudlify/index.mjs';
 import {serveStatic as ws, render as renderView, internalFetch} from './webserver.mjs';
 import Workflow from './workflow/engine.mjs';
+import { generateOpenApiSpec } from './openapi/generator.mjs';
+import { generateSwaggerHtml } from './openapi/swagger-ui.mjs';
 
 function createRoute(str) {
   if(str instanceof RegExp) {
@@ -22,29 +24,54 @@ class Codehooks {
   workers = {};
   realtime = {};
   startup = {};
-  
+  openApiMeta = {};  // Store route documentation metadata
+
+  // Extract OpenAPI metadata from route handlers
+  _extractOpenApiMeta = (routeKey, hooks) => {
+    for (const hook of hooks) {
+      if (hook && hook._openApiSpec) {
+        this.openApiMeta[routeKey] = {
+          ...this.openApiMeta[routeKey],
+          ...hook._openApiSpec
+        };
+      }
+    }
+  };
+
   post = (path, ...hook) => {
-    this.routes[`POST ${createRoute(path)}`] = hook;
+    const routeKey = `POST ${createRoute(path)}`;
+    this.routes[routeKey] = hook;
+    this._extractOpenApiMeta(routeKey, hook);
   };
 
   get = (path, ...hook) => {
-    this.routes[`GET ${createRoute(path)}`] = hook;
+    const routeKey = `GET ${createRoute(path)}`;
+    this.routes[routeKey] = hook;
+    this._extractOpenApiMeta(routeKey, hook);
   };
 
   put = (path, ...hook) => {
-    this.routes[`PUT ${createRoute(path)}`] = hook;
+    const routeKey = `PUT ${createRoute(path)}`;
+    this.routes[routeKey] = hook;
+    this._extractOpenApiMeta(routeKey, hook);
   };
 
   patch = (path, ...hook) => {
-    this.routes[`PATCH ${createRoute(path)}`] = hook;
+    const routeKey = `PATCH ${createRoute(path)}`;
+    this.routes[routeKey] = hook;
+    this._extractOpenApiMeta(routeKey, hook);
   };
 
   delete = (path, ...hook) => {
-    this.routes[`DELETE ${createRoute(path)}`] = hook;
+    const routeKey = `DELETE ${createRoute(path)}`;
+    this.routes[routeKey] = hook;
+    this._extractOpenApiMeta(routeKey, hook);
   };
 
   all = (path, ...hook) => {
-    this.routes[`* ${createRoute(path)}`] = hook;
+    const routeKey = `* ${createRoute(path)}`;
+    this.routes[routeKey] = hook;
+    this._extractOpenApiMeta(routeKey, hook);
   };
 
   auth = (path, ...hook) => {
@@ -110,6 +137,46 @@ class Codehooks {
     return crud(Codehooks.getInstance(), schema, options);
   }
 
+  /**
+   * Enable OpenAPI documentation
+   * @param {object} config - OpenAPI configuration
+   * @param {string} [uiPath='/docs'] - Path to serve Swagger UI
+   * @returns {Codehooks} this for chaining
+   */
+  openapi = (config = {}, uiPath = '/docs') => {
+    const specPath = config.specPath || '/openapi.json';
+
+    // Store OpenAPI config
+    this.set('_openapi_config', config);
+
+    // Route: Serve OpenAPI JSON spec
+    this.get(specPath, async (req, res) => {
+      const spec = await generateOpenApiSpec(this, config);
+      res.set('Content-Type', 'application/json');
+      res.json(spec);
+    });
+
+    // Route: Serve Swagger UI HTML
+    this.get(uiPath, async (req, res) => {
+      // Build spec URL relative to current path
+      const specUrl = specPath;
+
+      const html = generateSwaggerHtml(specUrl, {
+        title: config.info?.title || 'API Documentation',
+        ...config.swaggerUi
+      });
+
+      res.set('Content-Type', 'text/html');
+      res.send(html);
+    });
+
+    // Bypass auth for doc routes
+    this.auth(specPath, (req, res, next) => next());
+    this.auth(uiPath, (req, res, next) => next());
+
+    return this;
+  }
+
   realtime = (path, ...hook) => {
     this.realtime[path] = hook;
     if (hook) {
@@ -206,6 +273,8 @@ export const app = _coho;
 export {
   Workflow
 };
+// OpenAPI documentation helpers
+export { openapi, response, body, param, query, header } from './openapi/index.mjs';
 export const realtime = {
   createChannel: (path, ...hook) => {
     Codehooks.getInstance().realtime(path, ...hook);