next-openapi-gen 0.7.11 → 0.8.0

package/README.md

@@ -6,8 +6,9 @@ Automatically generate OpenAPI 3.0 documentation from Next.js projects, with sup
 
 - ✅ Automatic OpenAPI documentation generation from Next.js code
 - ✅ Support for Next.js App Router (including `/api/users/[id]/route.ts` routes)
-- ✅ Zod schemas support
 - ✅ TypeScript types support
+- ✅ Zod schemas support
+- ✅ Drizzle-Zod support - Generate schemas from Drizzle ORM tables 🆕
 - ✅ JSDoc comments support
 - ✅ Multiple UI interfaces: `Scalar`, `Swagger`, `Redoc`, `Stoplight` and `Rapidoc` available at `/api-docs` url
 - ✅ Path parameters detection (`/users/{id}`)
@@ -152,6 +153,44 @@ export async function GET(
 }
 ```
 
+### With Drizzle-Zod
+
+```typescript
+// src/db/schema.ts - Define your Drizzle table
+import { pgTable, serial, varchar, text } from "drizzle-orm/pg-core";
+
+export const posts = pgTable("posts", {
+  id: serial("id").primaryKey(),
+  title: varchar("title", { length: 255 }).notNull(),
+  content: text("content").notNull(),
+});
+
+// src/schemas/post.ts - Generate Zod schema with drizzle-zod
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { posts } from "@/db/schema";
+
+export const CreatePostSchema = createInsertSchema(posts, {
+  title: (schema) => schema.title.min(5).max(255).describe("Post title"),
+  content: (schema) => schema.content.min(10).describe("Post content"),
+});
+
+export const PostResponseSchema = createSelectSchema(posts);
+
+// src/app/api/posts/route.ts - Use in your API route
+/**
+ * Create a new post
+ * @description Create a new blog post with Drizzle-Zod validation
+ * @body CreatePostSchema
+ * @response 201:PostResponseSchema
+ * @openapi
+ */
+export async function POST(request: NextRequest) {
+  const body = await request.json();
+  const validated = CreatePostSchema.parse(body);
+  // Implementation...
+}
+```
+
 ## JSDoc Documentation Tags
 
 | Tag                    | Description                                                                                                              |
@@ -694,6 +733,64 @@ type User = z.infer<typeof UserSchema>;
 // The library will be able to recognize this schema by reference `UserSchema` or `User` type.
 ```
 
+### Drizzle-Zod Support
+
+The library fully supports **drizzle-zod** for generating Zod schemas from Drizzle ORM table definitions. This provides a single source of truth for your database schema, validation, and API documentation.
+
+**Supported Functions:**
+
+- `createInsertSchema()` - Generate schema for inserts
+- `createSelectSchema()` - Generate schema for selects
+- `createUpdateSchema()` - Generate schema for updates
+
+**Features:**
+
+- ✅ Automatic field extraction from refinements
+- ✅ Validation method conversion (min, max, email, url, etc.)
+- ✅ Optional/nullable field detection
+- ✅ Intelligent type mapping based on field names
+- ✅ Full OpenAPI schema generation
+
+**Example:**
+
+```typescript
+import { createInsertSchema } from "drizzle-zod";
+import { posts } from "@/db/schema";
+
+export const CreatePostSchema = createInsertSchema(posts, {
+  title: (schema) => schema.title.min(5).max(255),
+  content: (schema) => schema.content.min(10),
+  published: (schema) => schema.published.optional(),
+});
+```
+
+See the [complete Drizzle-Zod example](./examples/next15-app-drizzle-zod) for a full working implementation with a blog API.
+
+## Examples
+
+This repository includes several complete example projects:
+
+### 📦 Available Examples
+
+| Example                                                         | Description                | Features                                        |
+| --------------------------------------------------------------- | -------------------------- | ----------------------------------------------- |
+| **[next15-app-zod](./examples/next15-app-zod)**                 | Zod schemas example        | Users, Products, Orders API with Zod validation |
+| **[next15-app-drizzle-zod](./examples/next15-app-drizzle-zod)** | Drizzle-Zod integration 🆕 | Blog API with Drizzle ORM + drizzle-zod         |
+| **[next15-app-typescript](./examples/next15-app-typescript)**   | TypeScript types           | API with pure TypeScript type definitions       |
+| **[next15-app-scalar](./examples/next15-app-scalar)**           | Scalar UI                  | Modern API documentation interface              |
+| **[next15-app-swagger](./examples/next15-app-swagger)**         | Swagger UI                 | Classic Swagger documentation                   |
+
+### 🚀 Running Examples
+
+```bash
+cd examples/next15-app-drizzle-zod
+npm install
+npm run openapi:generate
+npm run dev
+```
+
+Visit `http://localhost:3000/api-docs` to see the generated documentation.
+
 ## Available UI providers
 
 <div align="center">
@@ -727,6 +824,16 @@ type User = z.infer<typeof UserSchema>;
 </table>
 </div>
 
+## Learn More
+
+- **[Drizzle-Zod Example](./examples/next15-app-drizzle-zod)** - Complete example with Drizzle ORM integration
+- **[Drizzle ORM](https://orm.drizzle.team/)** - TypeScript ORM for SQL databases
+- **[drizzle-zod](https://orm.drizzle.team/docs/zod)** - Zod schema generator for Drizzle
+- **[Zod Documentation](https://zod.dev/)** - TypeScript-first schema validation
+- **[Next.js Documentation](https://nextjs.org/docs)** - React framework documentation
+- **[OpenAPI Specification](https://swagger.io/specification/)** - OpenAPI 3.0 spec
+- **[Scalar Documentation](https://docs.scalar.com/)** - Modern API documentation UI
+
 ## License
 
 MIT

package/dist/lib/drizzle-zod-processor.js

@@ -0,0 +1,327 @@
+import * as t from "@babel/types";
+import { logger } from "./logger.js";
+/**
+ * Processor for drizzle-zod schemas
+ *
+ * Drizzle-zod is a library that generates Zod schemas from Drizzle ORM table definitions.
+ * It provides helper functions like:
+ * - createInsertSchema(tableDefinition, refinements)
+ * - createSelectSchema(tableDefinition, refinements)
+ *
+ * This processor extracts field definitions and refinements to generate OpenAPI schemas.
+ */
+export class DrizzleZodProcessor {
+    /**
+     * Known drizzle-zod helper function names
+     */
+    static DRIZZLE_ZOD_HELPERS = [
+        "createInsertSchema",
+        "createSelectSchema",
+        "createUpdateSchema",
+    ];
+    /**
+     * Process a drizzle-zod schema node
+     *
+     * @param node - The CallExpression node representing a drizzle-zod function call
+     * @returns OpenAPI schema object
+     */
+    static processSchema(node) {
+        const functionName = t.isIdentifier(node.callee)
+            ? node.callee.name
+            : "unknown";
+        logger.debug(`Processing drizzle-zod schema: ${functionName}`);
+        const schema = {
+            type: "object",
+            properties: {},
+            required: [],
+        };
+        // Check if there's a refinements object (second argument)
+        if (node.arguments.length > 1 && t.isObjectExpression(node.arguments[1])) {
+            const refinements = node.arguments[1];
+            // Process each property in the refinements object
+            refinements.properties.forEach((prop) => {
+                if (t.isObjectProperty(prop) || t.isObjectMethod(prop)) {
+                    const key = this.extractPropertyKey(prop);
+                    if (!key)
+                        return;
+                    // The value is typically an arrow function: (schema) => schema.field.method()
+                    if (t.isObjectProperty(prop) &&
+                        t.isArrowFunctionExpression(prop.value)) {
+                        const arrowFunc = prop.value;
+                        const fieldSchema = this.extractFieldSchema(arrowFunc.body);
+                        if (fieldSchema) {
+                            schema.properties[key] = fieldSchema;
+                            // Determine if field is required based on schema modifiers
+                            if (!this.isFieldOptional(arrowFunc.body)) {
+                                schema.required.push(key);
+                            }
+                        }
+                    }
+                }
+            });
+        }
+        // If no properties were extracted, return a generic object schema
+        if (Object.keys(schema.properties).length === 0) {
+            logger.debug("No properties extracted from drizzle-zod schema, returning generic object");
+            return { type: "object" };
+        }
+        return schema;
+    }
+    /**
+     * Extract property key from object property or method
+     */
+    static extractPropertyKey(prop) {
+        if (t.isIdentifier(prop.key)) {
+            return prop.key.name;
+        }
+        if (t.isStringLiteral(prop.key)) {
+            return prop.key.value;
+        }
+        return null;
+    }
+    /**
+     * Extract OpenAPI schema from a drizzle-zod field refinement
+     *
+     * Handles patterns like:
+     * - schema.field
+     * - schema.field.min(1)
+     * - schema.field.min(1).max(100).email()
+     */
+    static extractFieldSchema(node) {
+        // Handle member expressions like: schema.field
+        if (t.isMemberExpression(node)) {
+            if (t.isIdentifier(node.property)) {
+                const fieldType = node.property.name;
+                return this.mapFieldTypeToOpenApi(fieldType);
+            }
+        }
+        // Handle call expressions (chained methods like schema.field.min(1).max(100))
+        if (t.isCallExpression(node)) {
+            const baseSchema = this.extractFieldSchema(t.isMemberExpression(node.callee) ? node.callee.object : node);
+            if (baseSchema && t.isMemberExpression(node.callee)) {
+                const methodName = t.isIdentifier(node.callee.property)
+                    ? node.callee.property.name
+                    : null;
+                if (methodName) {
+                    return this.applyZodMethod(baseSchema, methodName, node.arguments);
+                }
+            }
+            return baseSchema;
+        }
+        return null;
+    }
+    /**
+     * Check if a drizzle-zod field is optional
+     */
+    static isFieldOptional(node) {
+        if (t.isCallExpression(node) && t.isMemberExpression(node.callee)) {
+            const methodName = t.isIdentifier(node.callee.property)
+                ? node.callee.property.name
+                : null;
+            if (methodName === "optional" ||
+                methodName === "nullable" ||
+                methodName === "nullish") {
+                return true;
+            }
+            // Check parent chain recursively
+            return this.isFieldOptional(node.callee.object);
+        }
+        return false;
+    }
+    /**
+     * Map Drizzle field types to OpenAPI types
+     *
+     * This provides intelligent mapping based on common field naming patterns.
+     * For more accurate type detection, the drizzle table schema would need to be analyzed.
+     */
+    static mapFieldTypeToOpenApi(fieldType) {
+        // Common mappings based on field naming conventions
+        const lowercaseField = fieldType.toLowerCase();
+        // String types
+        if (lowercaseField.includes("title") ||
+            lowercaseField.includes("name") ||
+            lowercaseField.includes("description") ||
+            lowercaseField.includes("content") ||
+            lowercaseField.includes("text") ||
+            lowercaseField.includes("slug") ||
+            lowercaseField.includes("email") ||
+            lowercaseField.includes("url") ||
+            lowercaseField.includes("phone")) {
+            const schema = { type: "string" };
+            // Add format hints
+            if (lowercaseField.includes("email")) {
+                schema.format = "email";
+            }
+            else if (lowercaseField.includes("url") ||
+                lowercaseField.includes("uri")) {
+                schema.format = "uri";
+            }
+            else if (lowercaseField.includes("uuid")) {
+                schema.format = "uuid";
+            }
+            return schema;
+        }
+        // Integer types
+        if (lowercaseField.includes("id") ||
+            lowercaseField.includes("count") ||
+            lowercaseField.includes("stock") ||
+            lowercaseField.includes("quantity") ||
+            lowercaseField.includes("age") ||
+            lowercaseField.includes("year")) {
+            return { type: "integer" };
+        }
+        // Number types
+        if (lowercaseField.includes("price") ||
+            lowercaseField.includes("amount") ||
+            lowercaseField.includes("rate") ||
+            lowercaseField.includes("percent")) {
+            return { type: "number" };
+        }
+        // Boolean types
+        if (lowercaseField.startsWith("is") ||
+            lowercaseField.startsWith("has") ||
+            lowercaseField.includes("active") ||
+            lowercaseField.includes("enabled") ||
+            lowercaseField.includes("published")) {
+            return { type: "boolean" };
+        }
+        // Date/time types
+        if (lowercaseField.includes("date") ||
+            lowercaseField.includes("time") ||
+            lowercaseField.includes("createdat") ||
+            lowercaseField.includes("updatedat") ||
+            lowercaseField.includes("deletedat")) {
+            return { type: "string", format: "date-time" };
+        }
+        // Default to string for unknown types
+        return { type: "string" };
+    }
+    /**
+     * Apply a Zod validation method to a schema
+     *
+     * Translates Zod validation methods to OpenAPI constraints:
+     * - min/max for strings become minLength/maxLength
+     * - min/max for numbers become minimum/maximum
+     * - email/url/uuid become format constraints
+     */
+    static applyZodMethod(schema, methodName, args) {
+        const result = { ...schema };
+        switch (methodName) {
+            case "min":
+                if (args.length > 0 && t.isNumericLiteral(args[0])) {
+                    if (schema.type === "string") {
+                        result.minLength = args[0].value;
+                    }
+                    else if (schema.type === "number" || schema.type === "integer") {
+                        result.minimum = args[0].value;
+                    }
+                    else if (schema.type === "array") {
+                        result.minItems = args[0].value;
+                    }
+                }
+                break;
+            case "max":
+                if (args.length > 0 && t.isNumericLiteral(args[0])) {
+                    if (schema.type === "string") {
+                        result.maxLength = args[0].value;
+                    }
+                    else if (schema.type === "number" || schema.type === "integer") {
+                        result.maximum = args[0].value;
+                    }
+                    else if (schema.type === "array") {
+                        result.maxItems = args[0].value;
+                    }
+                }
+                break;
+            case "length":
+                if (args.length > 0 && t.isNumericLiteral(args[0])) {
+                    if (schema.type === "string") {
+                        result.minLength = args[0].value;
+                        result.maxLength = args[0].value;
+                    }
+                    else if (schema.type === "array") {
+                        result.minItems = args[0].value;
+                        result.maxItems = args[0].value;
+                    }
+                }
+                break;
+            case "email":
+                result.format = "email";
+                break;
+            case "url":
+                result.format = "uri";
+                break;
+            case "uuid":
+                result.format = "uuid";
+                break;
+            case "datetime":
+                result.format = "date-time";
+                break;
+            case "regex":
+                if (args.length > 0) {
+                    // Try to extract pattern from regex literal
+                    if (t.isRegExpLiteral(args[0])) {
+                        result.pattern = args[0].pattern;
+                    }
+                }
+                break;
+            case "positive":
+                if (schema.type === "number" || schema.type === "integer") {
+                    result.minimum = 0;
+                    result.exclusiveMinimum = true;
+                }
+                break;
+            case "nonnegative":
+                if (schema.type === "number" || schema.type === "integer") {
+                    result.minimum = 0;
+                }
+                break;
+            case "negative":
+                if (schema.type === "number" || schema.type === "integer") {
+                    result.maximum = 0;
+                    result.exclusiveMaximum = true;
+                }
+                break;
+            case "nonpositive":
+                if (schema.type === "number" || schema.type === "integer") {
+                    result.maximum = 0;
+                }
+                break;
+            case "int":
+                result.type = "integer";
+                break;
+            case "optional":
+            case "nullable":
+            case "nullish":
+                // These are handled by the isFieldOptional check
+                // Don't modify the schema here
+                break;
+            case "describe":
+                if (args.length > 0 && t.isStringLiteral(args[0])) {
+                    result.description = args[0].value;
+                }
+                break;
+            case "default":
+                if (args.length > 0) {
+                    // Extract default value
+                    if (t.isStringLiteral(args[0])) {
+                        result.default = args[0].value;
+                    }
+                    else if (t.isNumericLiteral(args[0])) {
+                        result.default = args[0].value;
+                    }
+                    else if (t.isBooleanLiteral(args[0])) {
+                        result.default = args[0].value;
+                    }
+                }
+                break;
+        }
+        return result;
+    }
+    /**
+     * Check if a function name is a drizzle-zod helper
+     */
+    static isDrizzleZodHelper(name) {
+        return this.DRIZZLE_ZOD_HELPERS.includes(name);
+    }
+}

package/dist/lib/zod-converter.js

@@ -6,6 +6,7 @@ import * as t from "@babel/types";
 const traverse = traverseModule.default || traverseModule;
 import { parseTypeScriptFile } from "./utils.js";
 import { logger } from "./logger.js";
+import { DrizzleZodProcessor } from "./drizzle-zod-processor.js";
 /**
  * Class for converting Zod schemas to OpenAPI specifications
  */
@@ -15,6 +16,7 @@ export class ZodSchemaConverter {
     processingSchemas = new Set();
     processedModules = new Set();
     typeToSchemaMapping = {};
+    drizzleZodImports = new Set();
     constructor(schemaDir) {
         this.schemaDir = path.resolve(schemaDir);
     }
@@ -157,6 +159,15 @@ export class ZodSchemaConverter {
                 ImportDeclaration: (path) => {
                     // Keep track of imports to resolve external schemas
                     const source = path.node.source.value;
+                    // Track drizzle-zod imports
+                    if (source === "drizzle-zod") {
+                        path.node.specifiers.forEach((specifier) => {
+                            if (t.isImportSpecifier(specifier) ||
+                                t.isImportDefaultSpecifier(specifier)) {
+                                this.drizzleZodImports.add(specifier.local.name);
+                            }
+                        });
+                    }
                     // Process each import specifier
                     path.node.specifiers.forEach((specifier) => {
                         if (t.isImportSpecifier(specifier) ||
@@ -173,8 +184,17 @@ export class ZodSchemaConverter {
                             if (t.isIdentifier(declaration.id) &&
                                 declaration.id.name === schemaName &&
                                 declaration.init) {
-                                // Check if this is a call expression with .extend()
+                                // Check if this is a drizzle-zod helper function
                                 if (t.isCallExpression(declaration.init) &&
+                                    t.isIdentifier(declaration.init.callee) &&
+                                    this.drizzleZodImports.has(declaration.init.callee.name)) {
+                                    const schema = this.processZodNode(declaration.init);
+                                    if (schema) {
+                                        this.zodSchemas[schemaName] = schema;
+                                    }
+                                }
+                                // Check if this is a call expression with .extend()
+                                else if (t.isCallExpression(declaration.init) &&
                                     t.isMemberExpression(declaration.init.callee) &&
                                     t.isIdentifier(declaration.init.callee.property) &&
                                     declaration.init.callee.property.name === "extend") {
@@ -493,6 +513,12 @@ export class ZodSchemaConverter {
      * Process a Zod node and convert it to OpenAPI schema
      */
     processZodNode(node) {
+        // Handle drizzle-zod helper functions (e.g., createInsertSchema, createSelectSchema)
+        if (t.isCallExpression(node) &&
+            t.isIdentifier(node.callee) &&
+            this.drizzleZodImports.has(node.callee.name)) {
+            return DrizzleZodProcessor.processSchema(node);
+        }
         // Handle reference to another schema (e.g. UserBaseSchema.extend)
         if (t.isCallExpression(node) &&
             t.isMemberExpression(node.callee) &&
@@ -1471,6 +1497,20 @@ export class ZodSchemaConverter {
         try {
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
+            // First, collect all drizzle-zod imports
+            traverse(ast, {
+                ImportDeclaration: (path) => {
+                    const source = path.node.source.value;
+                    if (source === "drizzle-zod") {
+                        path.node.specifiers.forEach((specifier) => {
+                            if (t.isImportSpecifier(specifier) ||
+                                t.isImportDefaultSpecifier(specifier)) {
+                                this.drizzleZodImports.add(specifier.local.name);
+                            }
+                        });
+                    }
+                },
+            });
             // Collect all exported Zod schemas
             traverse(ast, {
                 ExportNamedDeclaration: (path) => {
@@ -1523,6 +1563,12 @@ export class ZodSchemaConverter {
      */
     isZodSchema(node) {
         if (t.isCallExpression(node)) {
+            // Check for drizzle-zod helper functions (e.g., createInsertSchema, createSelectSchema)
+            if (t.isIdentifier(node.callee) &&
+                this.drizzleZodImports.has(node.callee.name)) {
+                logger.debug(`[isZodSchema] Detected drizzle-zod function: ${node.callee.name}`);
+                return true;
+            }
             // Check direct z.method() calls
             if (t.isMemberExpression(node.callee) &&
                 t.isIdentifier(node.callee.object) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.7.11",
+  "version": "0.8.0",
   "description": "Automatically generate OpenAPI 3.0 documentation from Next.js projects, with support for Zod schemas and TypeScript types.",
   "type": "module",
   "main": "dist/index.js",