next-openapi-gen 0.5.0 → 0.5.2

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

@@ -43,6 +43,11 @@ export class SchemaProcessor {
         // Check if we should use Zod schemas
         if (this.schemaType === "zod") {
             console.log(`Looking for Zod schema: ${schemaName}`);
+            // Check type mapping first
+            const mappedSchemaName = this.zodSchemaConverter.typeToSchemaMapping[schemaName];
+            if (mappedSchemaName) {
+                console.log(`Type '${schemaName}' is mapped to Zod schema '${mappedSchemaName}'`);
+            }
             // Try to convert Zod schema
             const zodSchema = this.zodSchemaConverter.convertZodSchemaToOpenApi(schemaName);
             if (zodSchema) {
@@ -571,7 +576,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]
@@ -608,6 +613,7 @@ export class SchemaProcessor {
             });
         }
         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

@@ -11,6 +11,7 @@ export class ZodSchemaConverter {
     zodSchemas = {};
     processingSchemas = new Set();
     processedModules = new Set();
+    typeToSchemaMapping = {};
     constructor(schemaDir) {
         this.schemaDir = path.resolve(schemaDir);
     }
@@ -18,7 +19,17 @@ export class ZodSchemaConverter {
      * Find a Zod schema by name and convert it to OpenAPI spec
      */
     convertZodSchemaToOpenApi(schemaName) {
+        // Run pre-scan only one time
+        if (Object.keys(this.typeToSchemaMapping).length === 0) {
+            this.preScanForTypeMappings();
+        }
         console.log(`Looking for Zod schema: ${schemaName}`);
+        // Check mapped types
+        const mappedSchemaName = this.typeToSchemaMapping[schemaName];
+        if (mappedSchemaName) {
+            console.log(`Type '${schemaName}' is mapped to schema '${mappedSchemaName}'`);
+            schemaName = mappedSchemaName;
+        }
         // Check for circular references
         if (this.processingSchemas.has(schemaName)) {
             return { $ref: `#/components/schemas/${schemaName}` };
@@ -240,22 +251,51 @@ export class ZodSchemaConverter {
                 },
                 // For type aliases that reference Zod schemas
                 TSTypeAliasDeclaration: (path) => {
-                    if (t.isIdentifier(path.node.id) &&
-                        path.node.id.name === schemaName) {
-                        // Try to find if this is a z.infer<typeof SchemaName> pattern
+                    if (t.isIdentifier(path.node.id)) {
+                        const typeName = path.node.id.name;
                         if (t.isTSTypeReference(path.node.typeAnnotation) &&
-                            t.isIdentifier(path.node.typeAnnotation.typeName) &&
-                            path.node.typeAnnotation.typeName.name === "infer" &&
-                            path.node.typeAnnotation.typeParameters &&
-                            path.node.typeAnnotation.typeParameters.params.length > 0) {
-                            const param = path.node.typeAnnotation.typeParameters.params[0];
-                            if (t.isTSTypeQuery(param) && t.isIdentifier(param.exprName)) {
-                                const referencedSchemaName = param.exprName.name;
-                                // Find the referenced schema
-                                this.processFileForZodSchema(filePath, referencedSchemaName);
-                                if (this.zodSchemas[referencedSchemaName]) {
-                                    this.zodSchemas[schemaName] =
-                                        this.zodSchemas[referencedSchemaName];
+                            t.isTSQualifiedName(path.node.typeAnnotation.typeName) &&
+                            t.isIdentifier(path.node.typeAnnotation.typeName.left) &&
+                            path.node.typeAnnotation.typeName.left.name === "z" &&
+                            t.isIdentifier(path.node.typeAnnotation.typeName.right) &&
+                            path.node.typeAnnotation.typeName.right.name === "infer") {
+                            // Extract schema name from z.infer<typeof SchemaName>
+                            if (path.node.typeAnnotation.typeParameters &&
+                                path.node.typeAnnotation.typeParameters.params.length > 0) {
+                                const param = path.node.typeAnnotation.typeParameters.params[0];
+                                if (t.isTSTypeQuery(param) && t.isIdentifier(param.exprName)) {
+                                    const referencedSchemaName = param.exprName.name;
+                                    // Save mapping: TypeName -> SchemaName
+                                    this.typeToSchemaMapping[typeName] = referencedSchemaName;
+                                    console.log(`Mapped type '${typeName}' to schema '${referencedSchemaName}'`);
+                                    // Process the referenced schema if not already processed
+                                    if (!this.zodSchemas[referencedSchemaName]) {
+                                        this.processFileForZodSchema(filePath, referencedSchemaName);
+                                    }
+                                    // Use the referenced schema for this type
+                                    if (this.zodSchemas[referencedSchemaName]) {
+                                        this.zodSchemas[typeName] =
+                                            this.zodSchemas[referencedSchemaName];
+                                    }
+                                }
+                            }
+                        }
+                        if (path.node.id.name === schemaName) {
+                            // Try to find if this is a z.infer<typeof SchemaName> pattern
+                            if (t.isTSTypeReference(path.node.typeAnnotation) &&
+                                t.isIdentifier(path.node.typeAnnotation.typeName) &&
+                                path.node.typeAnnotation.typeName.name === "infer" &&
+                                path.node.typeAnnotation.typeParameters &&
+                                path.node.typeAnnotation.typeParameters.params.length > 0) {
+                                const param = path.node.typeAnnotation.typeParameters.params[0];
+                                if (t.isTSTypeQuery(param) && t.isIdentifier(param.exprName)) {
+                                    const referencedSchemaName = param.exprName.name;
+                                    // Find the referenced schema
+                                    this.processFileForZodSchema(filePath, referencedSchemaName);
+                                    if (this.zodSchemas[referencedSchemaName]) {
+                                        this.zodSchemas[schemaName] =
+                                            this.zodSchemas[referencedSchemaName];
+                                    }
                                 }
                             }
                         }
@@ -1058,4 +1098,87 @@ export class ZodSchemaConverter {
     getProcessedSchemas() {
         return this.zodSchemas;
     }
+    /**
+     * Pre-scan all files to build type mappings
+     */
+    preScanForTypeMappings() {
+        console.log("Pre-scanning for type mappings...");
+        // Scan route files
+        const routeFiles = this.findRouteFiles();
+        for (const routeFile of routeFiles) {
+            this.scanFileForTypeMappings(routeFile);
+        }
+        // Scan schema directory
+        this.scanDirectoryForTypeMappings(this.schemaDir);
+    }
+    /**
+     * Scan a single file for type mappings
+     */
+    scanFileForTypeMappings(filePath) {
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            const ast = parse(content, {
+                sourceType: "module",
+                plugins: ["typescript", "decorators-legacy"],
+            });
+            traverse.default(ast, {
+                TSTypeAliasDeclaration: (path) => {
+                    if (t.isIdentifier(path.node.id)) {
+                        const typeName = path.node.id.name;
+                        // Check for z.infer<typeof SchemaName> pattern
+                        if (t.isTSTypeReference(path.node.typeAnnotation)) {
+                            const typeRef = path.node.typeAnnotation;
+                            // Handle both z.infer and just infer (when z is imported)
+                            let isInferType = false;
+                            if (t.isTSQualifiedName(typeRef.typeName) &&
+                                t.isIdentifier(typeRef.typeName.left) &&
+                                typeRef.typeName.left.name === "z" &&
+                                t.isIdentifier(typeRef.typeName.right) &&
+                                typeRef.typeName.right.name === "infer") {
+                                isInferType = true;
+                            }
+                            else if (t.isIdentifier(typeRef.typeName) &&
+                                typeRef.typeName.name === "infer") {
+                                isInferType = true;
+                            }
+                            if (isInferType &&
+                                typeRef.typeParameters &&
+                                typeRef.typeParameters.params.length > 0) {
+                                const param = typeRef.typeParameters.params[0];
+                                if (t.isTSTypeQuery(param) && t.isIdentifier(param.exprName)) {
+                                    const referencedSchemaName = param.exprName.name;
+                                    this.typeToSchemaMapping[typeName] = referencedSchemaName;
+                                    console.log(`Pre-scan: Mapped type '${typeName}' to schema '${referencedSchemaName}'`);
+                                }
+                            }
+                        }
+                    }
+                },
+            });
+        }
+        catch (error) {
+            console.error(`Error scanning file ${filePath} for type mappings:`, error);
+        }
+    }
+    /**
+     * Recursively scan directory for type mappings
+     */
+    scanDirectoryForTypeMappings(dir) {
+        try {
+            const files = fs.readdirSync(dir);
+            for (const file of files) {
+                const filePath = path.join(dir, file);
+                const stats = fs.statSync(filePath);
+                if (stats.isDirectory()) {
+                    this.scanDirectoryForTypeMappings(filePath);
+                }
+                else if (file.endsWith(".ts") || file.endsWith(".tsx")) {
+                    this.scanFileForTypeMappings(filePath);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`Error scanning directory ${dir} for type mappings:`, error);
+        }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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",