next-openapi-gen 0.7.9 → 0.7.11

package/README.md

@@ -63,25 +63,27 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
   "outputDir": "./public",
   "docsUrl": "/api-docs",
   "includeOpenApiRoutes": false,
+  "ignoreRoutes": [],
   "debug": false
 }
 ```
 
 ### Configuration Options
 
-| Option                 | Description                                                            |
-| ---------------------- | ---------------------------------------------------------------------- |
-| `apiDir`               | Path to the API directory                                              |
-| `schemaDir`            | Path to the types/schemas directory                                    |
-| `schemaType`           | Schema type: `"zod"` or `"typescript"`                                 |
-| `outputFile`           | Name of the OpenAPI output file                                        |
-| `outputDir`            | Directory where OpenAPI file will be generated (default: `"./public"`) |
-| `docsUrl`              | API documentation URL (for Swagger UI)                                 |
-| `includeOpenApiRoutes` | Whether to include only routes with @openapi tag                       |
-| `defaultResponseSet`   | Default error response set for all endpoints                           |
-| `responseSets`         | Named sets of error response codes                                     |
-| `errorConfig`          | Error schema configuration                                             |
-| `debug`                | Enable detailed logging during generation                              |
+| Option                 | Description                                                                |
+| ---------------------- | -------------------------------------------------------------------------- |
+| `apiDir`               | Path to the API directory                                                  |
+| `schemaDir`            | Path to the types/schemas directory                                        |
+| `schemaType`           | Schema type: `"zod"` or `"typescript"`                                     |
+| `outputFile`           | Name of the OpenAPI output file                                            |
+| `outputDir`            | Directory where OpenAPI file will be generated (default: `"./public"`)     |
+| `docsUrl`              | API documentation URL (for Swagger UI)                                     |
+| `includeOpenApiRoutes` | Whether to include only routes with @openapi tag                           |
+| `ignoreRoutes`         | Array of route patterns to exclude from documentation (supports wildcards) |
+| `defaultResponseSet`   | Default error response set for all endpoints                               |
+| `responseSets`         | Named sets of error response codes                                         |
+| `errorConfig`          | Error schema configuration                                                 |
+| `debug`                | Enable detailed logging during generation                                  |
 
 ## Documenting Your API
 
@@ -168,6 +170,7 @@ export async function GET(
 | `@tag`                 | Custom tag                                                                                                               |
 | `@deprecated`          | Marks the route as deprecated                                                                                            |
 | `@openapi`             | Marks the route for inclusion in documentation (if includeOpenApiRoutes is enabled)                                      |
+| `@ignore`              | Excludes the route from OpenAPI documentation                                                                            |
 
 ## CLI Usage
 
@@ -537,6 +540,48 @@ export async function PUT() {}
 }
 ```
 
+## Ignoring Routes
+
+You can exclude routes from OpenAPI documentation in two ways:
+
+### Using @ignore Tag
+
+Add the `@ignore` tag to any route you want to exclude:
+
+```typescript
+// src/app/api/internal/route.ts
+
+/**
+ * Internal route - not for documentation
+ * @ignore
+ */
+export async function GET() {
+  // This route will not appear in OpenAPI documentation
+}
+```
+
+### Using ignoreRoutes Configuration
+
+Add patterns to your `next.openapi.json` configuration file to exclude multiple routes at once:
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Next.js API",
+    "version": "1.0.0"
+  },
+  "apiDir": "src/app/api",
+  "ignoreRoutes": ["/internal/*", "/debug", "/admin/test/*"]
+}
+```
+
+Pattern matching supports wildcards:
+
+- `/internal/*` - Ignores all routes under `/internal/`
+- `/debug` - Ignores only the `/debug` route
+- `/admin/*/temp` - Ignores routes like `/admin/users/temp`, `/admin/posts/temp`
+
 ## Advanced Usage
 
 ### Automatic Path Parameter Detection

package/dist/lib/openapi-generator.js

@@ -17,7 +17,7 @@ export class OpenApiGenerator {
     }
     getConfig() {
         // @ts-ignore
-        const { apiDir, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, schemaType = "typescript", defaultResponseSet, responseSets, errorConfig, debug } = this.template;
+        const { apiDir, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, ignoreRoutes, schemaType = "typescript", defaultResponseSet, responseSets, errorConfig, debug } = this.template;
         return {
             apiDir: apiDir || "./src/app/api",
             schemaDir: schemaDir || "./src",
@@ -26,6 +26,7 @@ export class OpenApiGenerator {
             outputFile: outputFile || "openapi.json",
             outputDir: outputDir || "./public",
             includeOpenApiRoutes: includeOpenApiRoutes || false,
+            ignoreRoutes: ignoreRoutes || [],
             schemaType,
             defaultResponseSet,
             responseSets,

package/dist/lib/route-processor.js

@@ -1,7 +1,9 @@
 import * as t from "@babel/types";
 import fs from "fs";
 import path from "path";
-import traverse from "@babel/traverse";
+import traverseModule from "@babel/traverse";
+// Handle both ES modules and CommonJS
+const traverse = traverseModule.default || traverseModule;
 import { SchemaProcessor } from "./schema-processor.js";
 import { capitalize, extractJSDocComments, parseTypeScriptFile, extractPathParameters, getOperationId, } from "./utils.js";
 import { logger } from "./logger.js";
@@ -113,24 +115,49 @@ export class RouteProcessor {
     isRoute(varName) {
         return HTTP_METHODS.includes(varName);
     }
+    /**
+     * Check if a route should be ignored based on config patterns or @ignore tag
+     */
+    shouldIgnoreRoute(routePath, dataTypes) {
+        // Check if route has @ignore tag
+        if (dataTypes.isIgnored) {
+            return true;
+        }
+        // Check if route matches any ignore patterns
+        const ignorePatterns = this.config.ignoreRoutes || [];
+        if (ignorePatterns.length === 0) {
+            return false;
+        }
+        return ignorePatterns.some((pattern) => {
+            // Support wildcards
+            const regexPattern = pattern.replace(/\*/g, ".*").replace(/\//g, "\\/");
+            const regex = new RegExp(`^${regexPattern}$`);
+            return regex.test(routePath);
+        });
+    }
     processFile(filePath) {
         // Check if the file has already been processed
         if (this.processFileTracker[filePath])
             return;
         const content = fs.readFileSync(filePath, "utf-8");
         const ast = parseTypeScriptFile(content);
-        traverse.default(ast, {
+        traverse(ast, {
             ExportNamedDeclaration: (path) => {
                 const declaration = path.node.declaration;
                 if (t.isFunctionDeclaration(declaration) &&
                     t.isIdentifier(declaration.id)) {
                     const dataTypes = extractJSDocComments(path);
                     if (this.isRoute(declaration.id.name)) {
+                        const routePath = this.getRoutePath(filePath);
+                        // Skip if route should be ignored
+                        if (this.shouldIgnoreRoute(routePath, dataTypes)) {
+                            logger.debug(`Ignoring route: ${routePath}`);
+                            return;
+                        }
                         // Don't bother adding routes for processing if only including OpenAPI routes and the route is not OpenAPI
                         if (!this.config.includeOpenApiRoutes ||
                             (this.config.includeOpenApiRoutes && dataTypes.isOpenApi)) {
                             // Check for URL parameters in the route path
-                            const routePath = this.getRoutePath(filePath);
                             const pathParams = extractPathParameters(routePath);
                             // If we have path parameters but no pathParamsType defined, we should log a warning
                             if (pathParams.length > 0 && !dataTypes.pathParamsType) {
@@ -145,10 +172,15 @@ export class RouteProcessor {
                         if (t.isVariableDeclarator(decl) && t.isIdentifier(decl.id)) {
                             if (this.isRoute(decl.id.name)) {
                                 const dataTypes = extractJSDocComments(path);
+                                const routePath = this.getRoutePath(filePath);
+                                // Skip if route should be ignored
+                                if (this.shouldIgnoreRoute(routePath, dataTypes)) {
+                                    logger.debug(`Ignoring route: ${routePath}`);
+                                    return;
+                                }
                                 // Don't bother adding routes for processing if only including OpenAPI routes and the route is not OpenAPI
                                 if (!this.config.includeOpenApiRoutes ||
                                     (this.config.includeOpenApiRoutes && dataTypes.isOpenApi)) {
-                                    const routePath = this.getRoutePath(filePath);
                                     const pathParams = extractPathParameters(routePath);
                                     if (pathParams.length > 0 && !dataTypes.pathParamsType) {
                                         logger.debug(`Route ${routePath} contains path parameters ${pathParams.join(", ")} but no @pathParams type is defined.`);
@@ -278,15 +310,15 @@ export class RouteProcessor {
         this.swaggerPaths[routePath][method] = definition;
     }
     getRoutePath(filePath) {
+        // Normalize path separators first
+        const normalizedPath = filePath.replaceAll("\\", "/");
         // First, check if it's an app router path
-        if (filePath.includes("/app/api/")) {
+        if (normalizedPath.includes("/app/api/")) {
             // Get the relative path from the api directory
-            const apiDirPos = filePath.indexOf("/app/api/");
-            let relativePath = filePath.substring(apiDirPos + "/app/api".length);
+            const apiDirPos = normalizedPath.lastIndexOf("/app/api/");
+            let relativePath = normalizedPath.substring(apiDirPos + "/app/api".length);
             // Remove the /route.ts or /route.tsx suffix
             relativePath = relativePath.replace(/\/route\.tsx?$/, "");
-            // Convert directory separators to URL path format
-            relativePath = relativePath.replaceAll("\\", "/");
             // Remove Next.js route groups (folders in parentheses like (authenticated), (marketing))
             relativePath = relativePath.replace(/\/\([^)]+\)/g, "");
             // Convert Next.js dynamic route syntax to OpenAPI parameter syntax
@@ -296,10 +328,9 @@ export class RouteProcessor {
             return relativePath;
         }
         // For pages router or other formats
-        const suffixPath = filePath.split("api")[1];
+        const suffixPath = normalizedPath.split("api")[1];
         return suffixPath
             .replace(/route\.tsx?$/, "")
-            .replaceAll("\\", "/")
             .replace(/\/$/, "")
             .replace(/\/\([^)]+\)/g, "") // Remove route groups for pages router too
             .replace(/\/\[([^\]]+)\]/g, "/{$1}") // Replace [param] with {param}

package/dist/lib/schema-processor.js

@@ -1,7 +1,9 @@
 import fs from "fs";
 import path from "path";
-import traverse from "@babel/traverse";
+import traverseModule from "@babel/traverse";
 import * as t from "@babel/types";
+// Handle both ES modules and CommonJS
+const traverse = traverseModule.default || traverseModule;
 import { parseTypeScriptFile } from "./utils.js";
 import { ZodSchemaConverter } from "./zod-converter.js";
 import { logger } from "./logger.js";
@@ -96,7 +98,7 @@ export class SchemaProcessor {
         });
     }
     collectTypeDefinitions(ast, schemaName) {
-        traverse.default(ast, {
+        traverse(ast, {
             VariableDeclarator: (path) => {
                 if (t.isIdentifier(path.node.id, { name: schemaName })) {
                     const name = path.node.id.name;

package/dist/lib/utils.js

@@ -25,6 +25,7 @@ export function extractJSDocComments(path) {
     let bodyType = "";
     let auth = "";
     let isOpenApi = false;
+    let isIgnored = false;
     let deprecated = false;
     let bodyDescription = "";
     let contentType = "";
@@ -37,6 +38,9 @@ export function extractJSDocComments(path) {
         comments.forEach((comment) => {
             const commentValue = cleanComment(comment.value);
             isOpenApi = commentValue.includes("@openapi");
+            if (commentValue.includes("@ignore")) {
+                isIgnored = true;
+            }
             if (commentValue.includes("@deprecated")) {
                 deprecated = true;
             }
@@ -143,6 +147,7 @@ export function extractJSDocComments(path) {
         pathParamsType,
         bodyType,
         isOpenApi,
+        isIgnored,
         deprecated,
         bodyDescription,
         contentType,
@@ -170,6 +175,7 @@ export function cleanSpec(spec) {
         "ui",
         "outputFile",
         "includeOpenApiRoutes",
+        "ignoreRoutes",
         "schemaType",
         "defaultResponseSet",
         "responseSets",

package/dist/lib/zod-converter.js

@@ -1,7 +1,9 @@
 import fs from "fs";
 import path from "path";
-import traverse from "@babel/traverse";
+import traverseModule from "@babel/traverse";
 import * as t from "@babel/types";
+// Handle both ES modules and CommonJS
+const traverse = traverseModule.default || traverseModule;
 import { parseTypeScriptFile } from "./utils.js";
 import { logger } from "./logger.js";
 /**
@@ -150,7 +152,7 @@ export class ZodSchemaConverter {
             // Create a map to store imported modules
             const importedModules = {};
             // Look for all exported Zod schemas
-            traverse.default(ast, {
+            traverse(ast, {
                 // Track imports for resolving local and imported schemas
                 ImportDeclaration: (path) => {
                     // Keep track of imports to resolve external schemas
@@ -457,7 +459,7 @@ export class ZodSchemaConverter {
         try {
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
-            traverse.default(ast, {
+            traverse(ast, {
                 ExportNamedDeclaration: (path) => {
                     if (t.isVariableDeclaration(path.node.declaration)) {
                         path.node.declaration.declarations.forEach((declaration) => {
@@ -549,6 +551,45 @@ export class ZodSchemaConverter {
                 return this.processZodPrimitive(node);
             }
         }
+        // Handle schema reference with method calls, e.g., Image.optional(), UserSchema.nullable()
+        if (t.isCallExpression(node) &&
+            t.isMemberExpression(node.callee) &&
+            t.isIdentifier(node.callee.object) &&
+            t.isIdentifier(node.callee.property) &&
+            node.callee.object.name !== "z" // Make sure it's not a z.* call
+        ) {
+            const schemaName = node.callee.object.name;
+            const methodName = node.callee.property.name;
+            // Process base schema first if not already processed
+            if (!this.zodSchemas[schemaName]) {
+                this.convertZodSchemaToOpenApi(schemaName);
+            }
+            // If the schema exists, create a reference and apply the method
+            if (this.zodSchemas[schemaName]) {
+                let schema = {
+                    allOf: [{ $ref: `#/components/schemas/${schemaName}` }],
+                };
+                // Apply method-specific transformations
+                switch (methodName) {
+                    case "optional":
+                    case "nullable":
+                    case "nullish":
+                        // Don't add nullable flag here as it would be at the wrong level
+                        // The fact that it's optional is handled by not including it in required array
+                        break;
+                    case "describe":
+                        if (node.arguments.length > 0 &&
+                            t.isStringLiteral(node.arguments[0])) {
+                            schema.description = node.arguments[0].value;
+                        }
+                        break;
+                    default:
+                        // For other methods, process as a chain
+                        return this.processZodChain(node);
+                }
+                return schema;
+            }
+        }
         // Handle chained methods, e.g., z.string().email().min(5)
         if (t.isCallExpression(node) &&
             t.isMemberExpression(node.callee) &&
@@ -1043,13 +1084,23 @@ export class ZodSchemaConverter {
         // Apply the current method
         switch (methodName) {
             case "optional":
-                schema.nullable = true;
+                // Don't add nullable for schema references wrapped in allOf
+                // as it doesn't make sense in that context
+                if (!schema.allOf) {
+                    schema.nullable = true;
+                }
                 break;
             case "nullable":
-                schema.nullable = true;
+                // Don't add nullable for schema references wrapped in allOf
+                if (!schema.allOf) {
+                    schema.nullable = true;
+                }
                 break;
             case "nullish": // Handles both null and undefined
-                schema.nullable = true;
+                // Don't add nullable for schema references wrapped in allOf
+                if (!schema.allOf) {
+                    schema.nullable = true;
+                }
                 break;
             case "describe":
                 if (node.arguments.length > 0 && t.isStringLiteral(node.arguments[0])) {
@@ -1353,7 +1404,7 @@ export class ZodSchemaConverter {
         try {
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
-            traverse.default(ast, {
+            traverse(ast, {
                 TSTypeAliasDeclaration: (path) => {
                     if (t.isIdentifier(path.node.id)) {
                         const typeName = path.node.id.name;
@@ -1421,7 +1472,7 @@ export class ZodSchemaConverter {
             const content = fs.readFileSync(filePath, "utf-8");
             const ast = parseTypeScriptFile(content);
             // Collect all exported Zod schemas
-            traverse.default(ast, {
+            traverse(ast, {
                 ExportNamedDeclaration: (path) => {
                     if (t.isVariableDeclaration(path.node.declaration)) {
                         path.node.declaration.declarations.forEach((declaration) => {

package/dist/openapi-template.js

@@ -93,5 +93,6 @@ export default {
     outputFile: "openapi.json",
     outputDir: "./public",
     includeOpenApiRoutes: false,
+    ignoreRoutes: [],
     debug: false,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "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",
@@ -13,8 +13,13 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsc",
-    "prepare": "npm run build"
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
   },
   "repository": {
     "type": "git",
@@ -51,6 +56,8 @@
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
-    "typescript": "^5.9.2"
+    "@vitest/ui": "^3.2.4",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   }
 }