next-openapi-gen 0.4.6 → 0.5.1

package/README.md

@@ -57,8 +57,8 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
     }
   ],
   "apiDir": "src/app/api",
-  "schemaDir": "src/types",
-  "schemaType": "typescript",  // or "zod" for Zod schemas
+  "schemaDir": "src/types", // or e.g. "src/schemas" for Zod schemas
+  "schemaType": "typescript", // or "zod" for Zod schemas
   "outputFile": "openapi.json",
   "docsUrl": "/api-docs",
   "includeOpenApiRoutes": false
@@ -67,13 +67,13 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
 
 ### Configuration Options
 
-| Option | Description |
-|-------|------|
-| `apiDir` | Path to the API directory |
-| `schemaDir` | Path to the types/schemas directory |
-| `schemaType` | Schema type: `"typescript"` or `"zod"` |
-| `outputFile` | Path to the OpenAPI output file |
-| `docsUrl` | API documentation URL (for Swagger UI) |
+| Option                 | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `apiDir`               | Path to the API directory                        |
+| `schemaDir`            | Path to the types/schemas directory              |
+| `schemaType`           | Schema type: `"typescript"` or `"zod"`           |
+| `outputFile`           | Path to the OpenAPI output file                  |
+| `docsUrl`              | API documentation URL (for Swagger UI)           |
 | `includeOpenApiRoutes` | Whether to include only routes with @openapi tag |
 
 ## Documenting Your API
@@ -83,7 +83,7 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
 ```typescript
 // src/app/api/users/[id]/route.ts
 
-import { NextRequest, NextResponse } from 'next/server';
+import { NextRequest, NextResponse } from "next/server";
 
 type UserParams = {
   id: string; // User ID
@@ -115,17 +115,17 @@ export async function GET(
 ```typescript
 // src/app/api/products/[id]/route.ts
 
-import { NextRequest, NextResponse } from 'next/server';
-import { z } from 'zod';
+import { NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
 
 export const ProductParams = z.object({
-  id: z.string().describe("Product ID")
+  id: z.string().describe("Product ID"),
 });
 
 export const ProductResponse = z.object({
   id: z.string().describe("Product ID"),
   name: z.string().describe("Product name"),
-  price: z.number().positive().describe("Product price")
+  price: z.number().positive().describe("Product price"),
 });
 
 /**
@@ -145,15 +145,16 @@ export async function GET(
 
 ## JSDoc Documentation Tags
 
-| Tag | Description |
-|-----|------|
-| `@desc` | Endpoint description |
-| `@pathParams` | Path parameters type/schema |
-| `@params` | Query parameters type/schema |
-| `@body` | Request body type/schema |
-| `@response` | Response type/schema |
-| `@auth` | Authorization type (`bearer`, `basic`, `apikey`) |
-| `@openapi` | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled) |
+| Tag           | Description                                                                         |
+| ------------- | ----------------------------------------------------------------------------------- |
+| `@desc`       | Endpoint description                                                                |
+| `@pathParams` | Path parameters type/schema                                                         |
+| `@params`     | Query parameters type/schema                                                        |
+| `@body`       | Request body type/schema                                                            |
+| `@response`   | Response type/schema                                                                |
+| `@auth`       | Authorization type (`bearer`, `basic`, `apikey`)                                    |
+| `@tag`        | Custom tag                                                                          |
+| `@openapi`    | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled) |
 
 ## CLI Usage
 
@@ -164,6 +165,7 @@ npx next-openapi-gen init
 ```
 
 This command will generate following elements:
+
 - Generate `next.openapi.json` configuration file
 - Install UI interface (default `Scalar`)
 - Add `/api-docs` page to display OpenAPI documentation
@@ -175,6 +177,7 @@ npx next-openapi-gen generate
 ```
 
 This command will generate OpenAPI documentation based on your API code:
+
 - Scan API directories for routes
 - Analyze types/schemas
 - Generate OpenAPI file (`openapi.json`) in `public` folder
@@ -182,7 +185,7 @@ This command will generate OpenAPI documentation based on your API code:
 
 ### 3. View API Documentation
 
-To see API documenation go to `http://localhost:3000/api-docs` 
+To see API documenation go to `http://localhost:3000/api-docs`
 
 ## Examples
 
@@ -198,7 +201,7 @@ type UserParams = {
 
 // Or Zod
 const UserParams = z.object({
-  id: z.string().describe("User ID")
+  id: z.string().describe("User ID"),
 });
 
 /**
@@ -225,7 +228,7 @@ type UsersQueryParams = {
 const UsersQueryParams = z.object({
   page: z.number().optional().describe("Page number"),
   limit: z.number().optional().describe("Results per page"),
-  search: z.string().optional().describe("Search phrase")
+  search: z.string().optional().describe("Search phrase"),
 });
 
 /**
@@ -252,7 +255,7 @@ type CreateUserBody = {
 const CreateUserBody = z.object({
   name: z.string().describe("Full name"),
   email: z.string().email().describe("Email address"),
-  password: z.string().min(8).describe("Password")
+  password: z.string().min(8).describe("Password"),
 });
 
 /**
@@ -281,7 +284,7 @@ const UserResponse = z.object({
   id: z.string().describe("User ID"),
   name: z.string().describe("Full name"),
   email: z.string().email().describe("Email address"),
-  createdAt: z.date().describe("Creation date")
+  createdAt: z.date().describe("Creation date"),
 });
 
 /**
@@ -326,14 +329,14 @@ If no type/schema is provided for path parameters, a default schema will be gene
 
 The library generates intelligent examples for parameters based on their name:
 
-| Parameter name | Example |
-|----------------|----------|
-| `id`, `*Id` | `"123"` or `123` |
-| `slug` | `"example-slug"` |
-| `uuid` | `"123e4567-e89b-12d3-a456-426614174000"` |
-| `email` | `"user@example.com"` |
-| `name` | `"example-name"` |
-| `date` | `"2023-01-01"` |
+| Parameter name | Example                                  |
+| -------------- | ---------------------------------------- |
+| `id`, `*Id`    | `"123"` or `123`                         |
+| `slug`         | `"example-slug"`                         |
+| `uuid`         | `"123e4567-e89b-12d3-a456-426614174000"` |
+| `email`        | `"user@example.com"`                     |
+| `name`         | `"example-name"`                         |
+| `date`         | `"2023-01-01"`                           |
 
 ## Advanced Zod Features
 
@@ -343,7 +346,12 @@ The library supports advanced Zod features such as:
 
 ```typescript
 // Zod validation chains are properly converted to OpenAPI schemas
-const EmailSchema = z.string().email().min(5).max(100).describe("Email address");
+const EmailSchema = z
+  .string()
+  .email()
+  .min(5)
+  .max(100)
+  .describe("Email address");
 
 // Converts to OpenAPI with email format, minLength and maxLength
 ```
@@ -352,11 +360,11 @@ const EmailSchema = z.string().email().min(5).max(100).describe("Email address")
 
 ```typescript
 // You can use TypeScript with Zod types
-import { z } from 'zod';
+import { z } from "zod";
 
 const UserSchema = z.object({
   id: z.string().uuid(),
-  name: z.string().min(2)
+  name: z.string().min(2),
 });
 
 // Use z.infer to create a TypeScript type

package/dist/lib/route-processor.js

@@ -109,7 +109,7 @@ export class RouteProcessor {
         const routePath = this.getRoutePath(filePath);
         const rootPath = capitalize(routePath.split("/")[1]);
         const operationId = getOperationId(routePath, method);
-        const { summary, description, auth, isOpenApi } = dataTypes;
+        const { tag, summary, description, auth, isOpenApi } = dataTypes;
         if (this.config.includeOpenApiRoutes && !isOpenApi) {
             // If flag is enabled and there is no @openapi tag, then skip path
             return;
@@ -122,7 +122,7 @@ export class RouteProcessor {
             operationId: operationId,
             summary: summary,
             description: description,
-            tags: [rootPath],
+            tags: [tag || rootPath],
             parameters: [],
         };
         // Add auth

package/dist/lib/schema-processor.js

@@ -26,6 +26,14 @@ export class SchemaProcessor {
      * Get all defined schemas (for components.schemas section)
      */
     getDefinedSchemas() {
+        // If using Zod, also include all processed Zod schemas
+        if (this.schemaType === "zod" && this.zodSchemaConverter) {
+            const zodSchemas = this.zodSchemaConverter.getProcessedSchemas();
+            return {
+                ...this.openapiDefinitions,
+                ...zodSchemas,
+            };
+        }
         return this.openapiDefinitions;
     }
     findSchemaDefinition(schemaName, contentType) {
@@ -441,10 +449,7 @@ export class SchemaProcessor {
         if (description) {
             options.description = description;
         }
-        if (this.contentType === "params") {
-            options.required = !isOptional;
-        }
-        else if (this.contentType === "body") {
+        if (this.contentType === "body") {
             options.nullable = isOptional;
         }
         return options;
@@ -526,7 +531,7 @@ export class SchemaProcessor {
                     schema: {
                         type: value.type,
                     },
-                    required: isPathParam ? true : value.required, // Path parameters are always required
+                    required: isPathParam ? true : !!value.required, // Path parameters are always required
                 };
                 if (value.enum) {
                     param.schema.enum = value.enum;
@@ -566,7 +571,7 @@ export class SchemaProcessor {
             },
         };
     }
-    getSchemaContent({ paramsType, pathParamsType, bodyType, responseType, }) {
+    getSchemaContent({ tag, paramsType, pathParamsType, bodyType, responseType, }) {
         let params = paramsType ? this.openapiDefinitions[paramsType] : {};
         let pathParams = pathParamsType
             ? this.openapiDefinitions[pathParamsType]
@@ -589,7 +594,21 @@ export class SchemaProcessor {
             this.findSchemaDefinition(responseType, "response");
             responses = this.openapiDefinitions[responseType] || {};
         }
+        if (this.schemaType === "zod") {
+            const schemasToProcess = [
+                paramsType,
+                pathParamsType,
+                bodyType,
+                responseType,
+            ].filter(Boolean);
+            schemasToProcess.forEach((schemaName) => {
+                if (!this.openapiDefinitions[schemaName]) {
+                    this.findSchemaDefinition(schemaName, "");
+                }
+            });
+        }
         return {
+            tag,
             params,
             pathParams,
             body,

package/dist/lib/utils.js

@@ -16,6 +16,7 @@ export function extractPathParameters(routePath) {
 }
 export function extractJSDocComments(path) {
     const comments = path.node.leadingComments;
+    let tag = "";
     let summary = "";
     let description = "";
     let paramsType = "";
@@ -50,6 +51,13 @@ export function extractJSDocComments(path) {
                 const regex = /@desc\s*(.*)/;
                 description = commentValue.match(regex)[1].trim();
             }
+            if (commentValue.includes("@tag")) {
+                const regex = /@tag\s*(.*)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    tag = match[1].trim();
+                }
+            }
             if (commentValue.includes("@params")) {
                 paramsType = extractTypeFromComment(commentValue, "@params");
             }
@@ -65,6 +73,7 @@ export function extractJSDocComments(path) {
         });
     }
     return {
+        tag,
         auth,
         summary,
         description,

package/dist/lib/zod-converter.js

@@ -9,7 +9,6 @@ import * as t from "@babel/types";
 export class ZodSchemaConverter {
     schemaDir;
     zodSchemas = {};
-    processedFiles = {};
     processingSchemas = new Set();
     processedModules = new Set();
     constructor(schemaDir) {
@@ -111,10 +110,6 @@ export class ZodSchemaConverter {
                 }
                 else if (file.endsWith(".ts") || file.endsWith(".tsx")) {
                     this.processFileForZodSchema(filePath, schemaName);
-                    // Stop searching if we found the schema
-                    if (this.zodSchemas[schemaName]) {
-                        break;
-                    }
                 }
             }
         }
@@ -126,12 +121,12 @@ export class ZodSchemaConverter {
      * Process a file to find Zod schema definitions
      */
     processFileForZodSchema(filePath, schemaName) {
-        // Skip if already processed
-        if (this.processedFiles[filePath])
-            return;
-        this.processedFiles[filePath] = true;
         try {
             const content = fs.readFileSync(filePath, "utf-8");
+            // Check if file contains schema we are looking for
+            if (!content.includes(schemaName)) {
+                return;
+            }
             // Parse the file
             const ast = parse(content, {
                 sourceType: "module",
@@ -161,9 +156,25 @@ export class ZodSchemaConverter {
                             if (t.isIdentifier(declaration.id) &&
                                 declaration.id.name === schemaName &&
                                 declaration.init) {
-                                const schema = this.processZodNode(declaration.init);
-                                if (schema) {
-                                    this.zodSchemas[schemaName] = schema;
+                                // Check if this is a call expression with .extend()
+                                if (t.isCallExpression(declaration.init) &&
+                                    t.isMemberExpression(declaration.init.callee) &&
+                                    t.isIdentifier(declaration.init.callee.property) &&
+                                    declaration.init.callee.property.name === "extend") {
+                                    const schema = this.processZodNode(declaration.init);
+                                    if (schema) {
+                                        this.zodSchemas[schemaName] = schema;
+                                    }
+                                }
+                                // Existing code for z.object({...})
+                                else if (t.isCallExpression(declaration.init) &&
+                                    t.isMemberExpression(declaration.init.callee) &&
+                                    t.isIdentifier(declaration.init.callee.object) &&
+                                    declaration.init.callee.object.name === "z") {
+                                    const schema = this.processZodNode(declaration.init);
+                                    if (schema) {
+                                        this.zodSchemas[schemaName] = schema;
+                                    }
                                 }
                             }
                         });
@@ -208,9 +219,22 @@ export class ZodSchemaConverter {
                     if (t.isIdentifier(path.node.id) &&
                         path.node.id.name === schemaName &&
                         path.node.init) {
-                        const schema = this.processZodNode(path.node.init);
-                        if (schema) {
-                            this.zodSchemas[schemaName] = schema;
+                        // Check if it is .extend()
+                        if (t.isCallExpression(path.node.init) &&
+                            t.isMemberExpression(path.node.init.callee) &&
+                            t.isIdentifier(path.node.init.callee.property) &&
+                            path.node.init.callee.property.name === "extend") {
+                            const schema = this.processZodNode(path.node.init);
+                            if (schema) {
+                                this.zodSchemas[schemaName] = schema;
+                            }
+                        }
+                        // Existing code
+                        else {
+                            const schema = this.processZodNode(path.node.init);
+                            if (schema) {
+                                this.zodSchemas[schemaName] = schema;
+                            }
                         }
                     }
                 },
@@ -243,10 +267,64 @@ export class ZodSchemaConverter {
             console.error(`Error processing file ${filePath} for schema ${schemaName}: ${error}`);
         }
     }
+    /**
+     * Process all exported schemas in a file, not just the one we're looking for
+     */
+    processAllSchemasInFile(filePath) {
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            const ast = parse(content, {
+                sourceType: "module",
+                plugins: ["typescript", "decorators-legacy"],
+            });
+            traverse.default(ast, {
+                ExportNamedDeclaration: (path) => {
+                    if (t.isVariableDeclaration(path.node.declaration)) {
+                        path.node.declaration.declarations.forEach((declaration) => {
+                            if (t.isIdentifier(declaration.id) &&
+                                declaration.init &&
+                                t.isCallExpression(declaration.init) &&
+                                t.isMemberExpression(declaration.init.callee) &&
+                                t.isIdentifier(declaration.init.callee.object) &&
+                                declaration.init.callee.object.name === "z") {
+                                const schemaName = declaration.id.name;
+                                if (!this.zodSchemas[schemaName] &&
+                                    !this.processingSchemas.has(schemaName)) {
+                                    this.processingSchemas.add(schemaName);
+                                    const schema = this.processZodNode(declaration.init);
+                                    if (schema) {
+                                        this.zodSchemas[schemaName] = schema;
+                                    }
+                                    this.processingSchemas.delete(schemaName);
+                                }
+                            }
+                        });
+                    }
+                },
+            });
+        }
+        catch (error) {
+            console.error(`Error processing all schemas in file ${filePath}: ${error}`);
+        }
+    }
     /**
      * Process a Zod node and convert it to OpenAPI schema
      */
     processZodNode(node) {
+        // Handle reference to another schema (e.g. UserBaseSchema.extend)
+        if (t.isCallExpression(node) &&
+            t.isMemberExpression(node.callee) &&
+            t.isIdentifier(node.callee.object) &&
+            t.isIdentifier(node.callee.property) &&
+            node.callee.property.name === "extend") {
+            const baseSchemaName = node.callee.object.name;
+            // Check if the base schema already exists
+            if (!this.zodSchemas[baseSchemaName]) {
+                // Try to find the basic pattern
+                this.convertZodSchemaToOpenApi(baseSchemaName);
+            }
+            return this.processZodChain(node);
+        }
         // Handle z.object({...})
         if (t.isCallExpression(node) &&
             t.isMemberExpression(node.callee) &&
@@ -461,7 +539,7 @@ export class ZodSchemaConverter {
         const objectExpression = node.arguments[0];
         const properties = {};
         const required = [];
-        objectExpression.properties.forEach((prop) => {
+        objectExpression.properties.forEach((prop, index) => {
             if (t.isObjectProperty(prop)) {
                 let propName;
                 // Handle both identifier and string literal keys
@@ -472,15 +550,56 @@ export class ZodSchemaConverter {
                     propName = prop.key.value;
                 }
                 else {
+                    console.log(`Skipping property ${index} - unsupported key type`);
                     return; // Skip if key is not identifier or string literal
                 }
+                // Check if the property value is an identifier (reference to another schema)
+                if (t.isIdentifier(prop.value)) {
+                    const referencedSchemaName = prop.value.name;
+                    // Try to find and convert the referenced schema
+                    if (!this.zodSchemas[referencedSchemaName]) {
+                        this.convertZodSchemaToOpenApi(referencedSchemaName);
+                    }
+                    // Create a reference
+                    properties[propName] = {
+                        $ref: `#/components/schemas/${referencedSchemaName}`,
+                    };
+                    required.push(propName); // Assuming it's required unless marked optional
+                }
+                // For array of schemas (like z.array(PaymentMethodSchema))
+                if (t.isCallExpression(prop.value) &&
+                    t.isMemberExpression(prop.value.callee) &&
+                    t.isIdentifier(prop.value.callee.object) &&
+                    prop.value.callee.object.name === "z" &&
+                    t.isIdentifier(prop.value.callee.property) &&
+                    prop.value.callee.property.name === "array" &&
+                    prop.value.arguments.length > 0 &&
+                    t.isIdentifier(prop.value.arguments[0])) {
+                    const itemSchemaName = prop.value.arguments[0].name;
+                    // Try to find and convert the referenced schema
+                    if (!this.zodSchemas[itemSchemaName]) {
+                        this.convertZodSchemaToOpenApi(itemSchemaName);
+                    }
+                    // Process as array with reference
+                    const arraySchema = this.processZodNode(prop.value);
+                    arraySchema.items = {
+                        $ref: `#/components/schemas/${itemSchemaName}`,
+                    };
+                    properties[propName] = arraySchema;
+                    const isOptional = this.isOptional(prop.value) || this.hasOptionalMethod(prop.value);
+                    if (!isOptional) {
+                        required.push(propName);
+                    }
+                }
                 // Process property value (a Zod schema)
                 const propSchema = this.processZodNode(prop.value);
                 if (propSchema) {
                     properties[propName] = propSchema;
                     // If the property is not marked as optional, add it to required list
+                    const isOptional = 
                     // @ts-ignore
-                    if (!this.isOptional(prop.value)) {
+                    this.isOptional(prop.value) || this.hasOptionalMethod(prop.value);
+                    if (!isOptional) {
                         required.push(propName);
                     }
                 }
@@ -534,7 +653,20 @@ export class ZodSchemaConverter {
             case "array":
                 let itemsType = { type: "string" };
                 if (node.arguments.length > 0) {
-                    itemsType = this.processZodNode(node.arguments[0]);
+                    // Check if argument is an identifier (schema reference)
+                    if (t.isIdentifier(node.arguments[0])) {
+                        const schemaName = node.arguments[0].name;
+                        // Try to find and convert the referenced schema
+                        if (!this.zodSchemas[schemaName]) {
+                            this.convertZodSchemaToOpenApi(schemaName);
+                        }
+                        // @ts-ignore
+                        itemsType = { $ref: `#/components/schemas/${schemaName}` };
+                    }
+                    else {
+                        // @ts-ignore
+                        itemsType = this.processZodNode(node.arguments[0]);
+                    }
                 }
                 schema = { type: "array", items: itemsType };
                 break;
@@ -806,7 +938,10 @@ export class ZodSchemaConverter {
             case "extend":
                 if (node.arguments.length > 0 &&
                     t.isObjectExpression(node.arguments[0])) {
-                    const extendedProps = this.processZodObject({
+                    // Get the base schema by processing the object that extend is called on
+                    const baseSchema = this.processZodNode(node.callee.object);
+                    // Process the extension object
+                    const extendNode = {
                         type: "CallExpression",
                         callee: {
                             type: "MemberExpression",
@@ -816,18 +951,28 @@ export class ZodSchemaConverter {
                             optional: false,
                         },
                         arguments: [node.arguments[0]],
-                    });
-                    if (extendedProps && extendedProps.properties) {
-                        schema.properties = {
-                            ...schema.properties,
-                            ...extendedProps.properties,
+                    };
+                    const extendedProps = this.processZodObject(extendNode);
+                    // Merge base schema and extensions
+                    if (baseSchema && baseSchema.properties) {
+                        schema = {
+                            type: "object",
+                            properties: {
+                                ...baseSchema.properties,
+                                ...(extendedProps?.properties || {}),
+                            },
+                            required: [
+                                ...(baseSchema.required || []),
+                                ...(extendedProps?.required || []),
+                            ].filter((item, index, arr) => arr.indexOf(item) === index), // Remove duplicates
                         };
-                        if (extendedProps.required) {
-                            schema.required = [
-                                ...(schema.required || []),
-                                ...extendedProps.required,
-                            ];
-                        }
+                        // Copy other properties from base schema
+                        if (baseSchema.description)
+                            schema.description = baseSchema.description;
+                    }
+                    else {
+                        console.log(`Warning: Could not resolve base schema for extend`);
+                        schema = extendedProps || { type: "object" };
                     }
                 }
                 break;

package/package.json

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