next-openapi-gen 1.3.0 → 1.4.0

package/README.md

@@ -276,19 +276,20 @@ Version guidance:
 
 ### Important options
 
-| Option                                | Purpose                                                          |
-| ------------------------------------- | ---------------------------------------------------------------- |
-| `openapi`                             | Target `3.0.0`, `3.1.0`, or `3.2.0` output                       |
-| `apiDir`                              | Route directory to scan                                          |
-| `routerType`                          | `"app"` or `"pages"`                                             |
-| `schemaDir`                           | Directory or directories to search for schemas/types             |
-| `schemaType`                          | `"zod"`, `"typescript"`, or both                                 |
-| `schemaFiles`                         | YAML/JSON OpenAPI fragments to merge into the generated document |
-| `includeOpenApiRoutes`                | Only include handlers tagged with `@openapi`                     |
-| `ignoreRoutes`                        | Exclude routes with wildcard support                             |
-| `defaultResponseSet` / `responseSets` | Reusable error-response groups                                   |
-| `errorConfig`                         | Shared error schema templates                                    |
-| `authPresets`                         | Override or extend the `@auth` keyword → scheme-name mapping     |
+| Option                                | Purpose                                                                                 |
+| ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `openapi`                             | Target `3.0.0`, `3.1.0`, or `3.2.0` output                                              |
+| `apiDir`                              | Route directory to scan                                                                 |
+| `routerType`                          | `"app"` or `"pages"`                                                                    |
+| `schemaDir`                           | Directory or directories to search for schemas/types                                    |
+| `schemaType`                          | `"zod"`, `"typescript"`, or both                                                        |
+| `schemaFiles`                         | YAML/JSON OpenAPI fragments to merge into the generated document                        |
+| `includeOpenApiRoutes`                | Only include handlers tagged with `@openapi`                                            |
+| `ignoreRoutes`                        | Exclude routes with wildcard support                                                    |
+| `excludeSchemas`                      | Exclude internal schemas from `components/schemas` by name or glob (e.g. `["*Params"]`) |
+| `defaultResponseSet` / `responseSets` | Reusable error-response groups                                                          |
+| `errorConfig`                         | Shared error schema templates                                                           |
+| `authPresets`                         | Override or extend the `@auth` keyword → scheme-name mapping                            |
 
 For a fuller setup guide, Pages Router notes, response sets, and route exclusion
 patterns, see [docs/getting-started.md](./docs/getting-started.md).
@@ -315,6 +316,7 @@ patterns, see [docs/getting-started.md](./docs/getting-started.md).
 | `@openapi`                 | Explicit inclusion marker when `includeOpenApiRoutes` is enabled                                        |
 | `@openapi-override`        | Deep-merge extra OpenAPI fields onto the operation                                                      |
 | `@ignore`                  | Exclude a route from generation                                                                         |
+| `@internal`                | Exclude a schema/type declaration from `components/schemas`                                             |
 | `@method`                  | Required HTTP method tag for Pages Router handlers                                                      |
 
 For the complete tag guide and usage recipes, see

package/dist/cli.js

@@ -588,122 +588,6 @@ import fse2 from "fs-extra";
 import path16 from "path";
 import fs12 from "fs";
 
-// ../openapi-core/dist/config/normalize.js
-function normalizeRouterType(routerType) {
-  return routerType ?? DEFAULT_ROUTER_TYPE;
-}
-function normalizeSchemaTypes(schemaType) {
-  const schemaBackends = Array.isArray(schemaType) ? schemaType : [schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE];
-  return [...new Set(schemaBackends)];
-}
-function normalizeOpenApiVersion(template) {
-  if (template.openapi.startsWith("3.2")) {
-    return "3.2";
-  }
-  if (template.openapi.startsWith("3.1")) {
-    return "3.1";
-  }
-  if (template.openapi.startsWith("4.")) {
-    return "4.0";
-  }
-  return DEFAULT_OPENAPI_VERSION;
-}
-function normalizeFrameworkKind(kind) {
-  switch (kind) {
-    case FrameworkKind.Nextjs:
-    case "next":
-      return FrameworkKind.Nextjs;
-    case FrameworkKind.Tanstack:
-    case "tanstack":
-      return FrameworkKind.Tanstack;
-    case FrameworkKind.ReactRouter:
-    case "react-router":
-      return FrameworkKind.ReactRouter;
-    default:
-      return FrameworkKind.Nextjs;
-  }
-}
-function normalizeFramework(config2, routerType) {
-  if (config2.framework) {
-    const frameworkKind = normalizeFrameworkKind(config2.framework.kind);
-    switch (frameworkKind) {
-      case FrameworkKind.Nextjs:
-        return {
-          ...config2.framework,
-          kind: frameworkKind,
-          router: config2.framework.router || routerType,
-          modulePath: config2.framework.modulePath || config2.framework.adapterPath || config2.next?.adapterPath,
-          adapterPath: config2.framework.adapterPath || config2.next?.adapterPath
-        };
-      case FrameworkKind.Tanstack:
-      case FrameworkKind.ReactRouter:
-        return {
-          ...config2.framework,
-          kind: frameworkKind,
-          modulePath: config2.framework.modulePath || config2.framework.adapterPath
-        };
-    }
-  }
-  return {
-    kind: FrameworkKind.Nextjs,
-    router: routerType,
-    modulePath: config2.next?.adapterPath,
-    adapterPath: config2.next?.adapterPath
-  };
-}
-function normalizeOpenApiConfig(template) {
-  const routerType = normalizeRouterType(template.routerType);
-  const schemaBackends = normalizeSchemaTypes(template.schemaType);
-  const openapiVersion = normalizeOpenApiVersion({
-    openapi: "openapi" in template ? template.openapi || "3.0.0" : "3.0.0"
-  });
-  return {
-    apiDir: template.apiDir ?? DEFAULT_API_DIR,
-    routerType,
-    schemaDir: template.schemaDir ?? DEFAULT_SCHEMA_DIR,
-    docsUrl: template.docsUrl ?? DEFAULT_DOCS_URL,
-    ui: template.ui ?? DEFAULT_UI,
-    outputFile: template.outputFile ?? DEFAULT_GENERATED_OPENAPI_FILENAME,
-    outputDir: template.outputDir ?? DEFAULT_OUTPUT_DIR,
-    includeOpenApiRoutes: template.includeOpenApiRoutes ?? DEFAULT_INCLUDE_OPENAPI_ROUTES,
-    ignoreRoutes: template.ignoreRoutes ?? [],
-    excludeSchemas: template.excludeSchemas ?? [],
-    schemaType: template.schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE,
-    schemaBackends,
-    schemaFiles: template.schemaFiles ?? [],
-    defaultResponseSet: template.defaultResponseSet,
-    responseSets: template.responseSets,
-    errorConfig: template.errorConfig,
-    errorDefinitions: template.errorDefinitions,
-    openapiVersion,
-    framework: normalizeFramework(template, routerType),
-    next: {
-      adapterPath: template.next?.adapterPath
-    },
-    diagnostics: template.diagnostics ?? { enabled: DEFAULT_DIAGNOSTICS_ENABLED },
-    debug: template.debug ?? DEFAULT_DEBUG
-  };
-}
-
-// ../openapi-core/dist/diagnostics/collector.js
-var DiagnosticsCollector = class {
-  diagnostics = [];
-  add(diagnostic) {
-    this.diagnostics.push(diagnostic);
-  }
-  getAll() {
-    return [...this.diagnostics];
-  }
-  hasAny() {
-    return this.diagnostics.length > 0;
-  }
-};
-
-// ../openapi-core/dist/openapi/document.js
-function createDocumentFromTemplate(template) {
-  return structuredClone(template);
-}
-
 // ../openapi-core/dist/shared/utils.js
 import { parse } from "@babel/parser";
 import * as t from "@babel/types";
@@ -1039,7 +923,7 @@ function parseJSDocBlock(commentValue, filePath) {
   result.cookieType = extractTypeFromComment(normalizedComment, "@cookie");
   const authValue = extractLineValue(normalizedComment, "@auth");
   if (authValue) {
-    result.auth = performAuthPresetReplacements(authValue);
+    result.auth = authValue;
   }
   const querystring = parseQuerystringTag(normalizedComment);
   if (querystring) {
@@ -1715,16 +1599,17 @@ var INTERNAL_OPENAPI_CONFIG_KEYS = [
   "next",
   "diagnostics",
   "debug",
+  "authPresets",
   "excludeSchemas"
 ];
-var AUTH_PRESET_REPLACEMENTS = {
+var DEFAULT_AUTH_PRESET_REPLACEMENTS = {
   bearer: "BearerAuth",
   basic: "BasicAuth",
   apikey: "ApiKeyAuth"
 };
-function performAuthPresetReplacements(authValue) {
+function performAuthPresetReplacements(authValue, presets = DEFAULT_AUTH_PRESET_REPLACEMENTS) {
   const authParts = authValue.split(",").map((part) => part.trim());
-  const mappedParts = authParts.map((part) => AUTH_PRESET_REPLACEMENTS[part.toLowerCase()] || part);
+  const mappedParts = authParts.map((part) => presets[part.toLowerCase()] || part);
   return mappedParts.join(",");
 }
 function getOperationId(routePath, method) {
@@ -1742,6 +1627,123 @@ function parseTypeScriptFile(content, options) {
   });
 }
 
+// ../openapi-core/dist/config/normalize.js
+function normalizeRouterType(routerType) {
+  return routerType ?? DEFAULT_ROUTER_TYPE;
+}
+function normalizeSchemaTypes(schemaType) {
+  const schemaBackends = Array.isArray(schemaType) ? schemaType : [schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE];
+  return [...new Set(schemaBackends)];
+}
+function normalizeOpenApiVersion(template) {
+  if (template.openapi.startsWith("3.2")) {
+    return "3.2";
+  }
+  if (template.openapi.startsWith("3.1")) {
+    return "3.1";
+  }
+  if (template.openapi.startsWith("4.")) {
+    return "4.0";
+  }
+  return DEFAULT_OPENAPI_VERSION;
+}
+function normalizeFrameworkKind(kind) {
+  switch (kind) {
+    case FrameworkKind.Nextjs:
+    case "next":
+      return FrameworkKind.Nextjs;
+    case FrameworkKind.Tanstack:
+    case "tanstack":
+      return FrameworkKind.Tanstack;
+    case FrameworkKind.ReactRouter:
+    case "react-router":
+      return FrameworkKind.ReactRouter;
+    default:
+      return FrameworkKind.Nextjs;
+  }
+}
+function normalizeFramework(config2, routerType) {
+  if (config2.framework) {
+    const frameworkKind = normalizeFrameworkKind(config2.framework.kind);
+    switch (frameworkKind) {
+      case FrameworkKind.Nextjs:
+        return {
+          ...config2.framework,
+          kind: frameworkKind,
+          router: config2.framework.router || routerType,
+          modulePath: config2.framework.modulePath || config2.framework.adapterPath || config2.next?.adapterPath,
+          adapterPath: config2.framework.adapterPath || config2.next?.adapterPath
+        };
+      case FrameworkKind.Tanstack:
+      case FrameworkKind.ReactRouter:
+        return {
+          ...config2.framework,
+          kind: frameworkKind,
+          modulePath: config2.framework.modulePath || config2.framework.adapterPath
+        };
+    }
+  }
+  return {
+    kind: FrameworkKind.Nextjs,
+    router: routerType,
+    modulePath: config2.next?.adapterPath,
+    adapterPath: config2.next?.adapterPath
+  };
+}
+function normalizeOpenApiConfig(template) {
+  const routerType = normalizeRouterType(template.routerType);
+  const schemaBackends = normalizeSchemaTypes(template.schemaType);
+  const openapiVersion = normalizeOpenApiVersion({
+    openapi: "openapi" in template ? template.openapi || "3.0.0" : "3.0.0"
+  });
+  return {
+    apiDir: template.apiDir ?? DEFAULT_API_DIR,
+    routerType,
+    schemaDir: template.schemaDir ?? DEFAULT_SCHEMA_DIR,
+    docsUrl: template.docsUrl ?? DEFAULT_DOCS_URL,
+    ui: template.ui ?? DEFAULT_UI,
+    outputFile: template.outputFile ?? DEFAULT_GENERATED_OPENAPI_FILENAME,
+    outputDir: template.outputDir ?? DEFAULT_OUTPUT_DIR,
+    includeOpenApiRoutes: template.includeOpenApiRoutes ?? DEFAULT_INCLUDE_OPENAPI_ROUTES,
+    ignoreRoutes: template.ignoreRoutes ?? [],
+    excludeSchemas: template.excludeSchemas ?? [],
+    schemaType: template.schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE,
+    schemaBackends,
+    schemaFiles: template.schemaFiles ?? [],
+    defaultResponseSet: template.defaultResponseSet,
+    responseSets: template.responseSets,
+    errorConfig: template.errorConfig,
+    errorDefinitions: template.errorDefinitions,
+    openapiVersion,
+    framework: normalizeFramework(template, routerType),
+    next: {
+      adapterPath: template.next?.adapterPath
+    },
+    diagnostics: template.diagnostics ?? { enabled: DEFAULT_DIAGNOSTICS_ENABLED },
+    authPresets: { ...DEFAULT_AUTH_PRESET_REPLACEMENTS, ...template.authPresets },
+    debug: template.debug ?? DEFAULT_DEBUG
+  };
+}
+
+// ../openapi-core/dist/diagnostics/collector.js
+var DiagnosticsCollector = class {
+  diagnostics = [];
+  add(diagnostic) {
+    this.diagnostics.push(diagnostic);
+  }
+  getAll() {
+    return [...this.diagnostics];
+  }
+  hasAny() {
+    return this.diagnostics.length > 0;
+  }
+};
+
+// ../openapi-core/dist/openapi/document.js
+function createDocumentFromTemplate(template) {
+  return structuredClone(template);
+}
+
 // ../openapi-core/dist/openapi/version-processor.js
 var DefaultOpenApiVersionProcessor = class {
   id;
@@ -2200,8 +2202,10 @@ function downgradeSchemaForOpenApi30(schema, mediaTypeName) {
     const nullableBranch = nextSchema.anyOf.find((item) => item.type === "null");
     const baseBranch = nextSchema.anyOf.find((item) => item.type !== "null");
     if (nullableBranch && baseBranch) {
+      const { anyOf: _anyOf, ...outerMeta } = nextSchema;
       nextSchema = {
         ...structuredClone(baseBranch),
+        ...outerMeta,
         nullable: true
       };
     }
@@ -4116,7 +4120,7 @@ function processZodLiteral(node, context) {
     return { type: "string", enum: [arg.value] };
   }
   if (t8.isNumericLiteral(arg)) {
-    return { type: "number", enum: [arg.value] };
+    return { type: Number.isInteger(arg.value) ? "integer" : "number", enum: [arg.value] };
   }
   if (t8.isBooleanLiteral(arg)) {
     return { type: "boolean", enum: [arg.value] };
@@ -4132,7 +4136,7 @@ function processZodLiteral(node, context) {
     if (typeof value === "string")
       return { type: "string", enum: [value] };
     if (typeof value === "number")
-      return { type: "number", enum: [value] };
+      return { type: Number.isInteger(value) ? "integer" : "number", enum: [value] };
     if (typeof value === "boolean")
       return { type: "boolean", enum: [value] };
     if (value === null)
@@ -4227,7 +4231,7 @@ function processZodTuple(node, processNode, context) {
     if (t8.isIdentifier(node.arguments[0]) && context?.resolveConstArrayValues) {
       const values = context.resolveConstArrayValues(node.arguments[0].name);
       if (values && values.length > 0) {
-        const prefixItems = values.map((value) => typeof value === "number" ? { type: "number", enum: [value] } : { type: "string", enum: [value] });
+        const prefixItems = values.map((value) => typeof value === "number" ? { type: Number.isInteger(value) ? "integer" : "number", enum: [value] } : { type: "string", enum: [value] });
         return {
           type: "array",
           prefixItems,
@@ -4271,7 +4275,7 @@ function processZodUnion(node, processNode, context) {
     if (t8.isIdentifier(node.arguments[0]) && context?.resolveConstArrayValues) {
       const values = context.resolveConstArrayValues(node.arguments[0].name);
       if (values && values.length > 0) {
-        const type = typeof values[0] === "number" ? "number" : "string";
+        const type = typeof values[0] === "number" ? Number.isInteger(values[0]) ? "integer" : "number" : "string";
         return { type, enum: values };
       }
     }
@@ -11718,8 +11722,17 @@ var ZodRuntimeExporter = class {
         return node.arguments[0] ? literal(this.buildLiteralValue(node.arguments[0])) : null;
       case "enum":
         return this.buildEnum(node);
-      case "array":
-        return node.arguments[0] && isProcessableNode(node.arguments[0]) ? array(this.buildSchema(node.arguments[0]) ?? unknown()) : array(unknown());
+      case "array": {
+        const arg = node.arguments[0];
+        if (!arg || !isProcessableNode(arg)) {
+          return array(unknown());
+        }
+        const itemSchema = this.buildSchema(arg);
+        if (!itemSchema) {
+          return null;
+        }
+        return array(itemSchema);
+      }
       case "strictObject": {
         const base = this.buildObject(node);
         return base && typeof base.strict === "function" ? base.strict() : base;
@@ -11851,13 +11864,17 @@ var ZodRuntimeExporter = class {
     if (node.arguments.length === 0 || !t9.isArrayExpression(node.arguments[0])) {
       return tuple([]);
     }
-    const items = node.arguments[0].elements.flatMap((element) => {
+    const items = [];
+    for (const element of node.arguments[0].elements) {
       if (!isProcessableNode(element)) {
-        return [];
+        return null;
       }
       const schema = this.buildSchema(element);
-      return schema ? [schema] : [];
-    });
+      if (!schema) {
+        return null;
+      }
+      items.push(schema);
+    }
     return tuple(items);
   }
   buildTemplateLiteral(node) {
@@ -12469,7 +12486,12 @@ var ZodSchemaConverter = class {
             if (this.isZodSchema(path25.node.init)) {
               const schema = this.processZodNode(path25.node.init);
               if (schema) {
-                this.storeResolvedSchema(schemaName, schema);
+                const overrideId = this.extractMetaIdFromNode(path25.node.init);
+                if (overrideId) {
+                  this.applyMetaIdOverride(schemaName, schema, overrideId, filePath);
+                } else {
+                  this.storeResolvedSchema(schemaName, schema);
+                }
               }
               return;
             }
@@ -12812,8 +12834,15 @@ var ZodSchemaConverter = class {
         };
         switch (methodName) {
           case "optional":
+            break;
           case "nullable":
           case "nullish":
+            schema = {
+              anyOf: [
+                { $ref: `#/components/schemas/${this.getSchemaReferenceName(schemaName)}` },
+                { type: "null" }
+              ]
+            };
             break;
           case "describe":
             if (node.arguments.length > 0 && t10.isStringLiteral(node.arguments[0])) {
@@ -13331,12 +13360,16 @@ var ZodSchemaConverter = class {
       case "optional":
         break;
       case "nullable":
-        if (!schema.allOf) {
+        if (schema.allOf) {
+          schema = { anyOf: [...schema.allOf, { type: "null" }] };
+        } else {
           schema.nullable = true;
         }
         break;
       case "nullish":
-        if (!schema.allOf) {
+        if (schema.allOf) {
+          schema = { anyOf: [...schema.allOf, { type: "null" }] };
+        } else {
           schema.nullable = true;
         }
         break;
@@ -13851,6 +13884,9 @@ var ZodSchemaConverter = class {
                   if (!this.getStoredSchema(schemaName)) {
                     logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                     this.processingSchemas.add(schemaName);
+                    this.currentFilePath = filePath;
+                    this.currentAST = ast;
+                    this.currentImports = importedModules;
                     const schema = this.processZodNode(declaration.init);
                     this.processingSchemas.delete(schemaName);
                     if (schema) {
@@ -13883,6 +13919,9 @@ var ZodSchemaConverter = class {
                 if (!this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
                   logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                   this.processingSchemas.add(schemaName);
+                  this.currentFilePath = filePath;
+                  this.currentAST = ast;
+                  this.currentImports = importedModules;
                   const schema = this.processZodNode(declaration.init);
                   this.processingSchemas.delete(schemaName);
                   if (schema) {
@@ -16753,11 +16792,16 @@ var ResponseProcessor = class {
 var OperationProcessor = class {
   schemaProcessor;
   responseProcessor;
+  authPresets;
   performanceProfile;
-  constructor(schemaProcessor, responseProcessor, performanceProfile) {
+  constructor(schemaProcessor, responseProcessor, options = {}) {
     this.schemaProcessor = schemaProcessor;
     this.responseProcessor = responseProcessor;
-    this.performanceProfile = performanceProfile;
+    this.authPresets = {
+      ...DEFAULT_AUTH_PRESET_REPLACEMENTS,
+      ...options.authPresets
+    };
+    this.performanceProfile = options.performanceProfile;
   }
   processOperation(varName, routePath, dataTypes, pathParamNames = []) {
     const method = varName.toLowerCase();
@@ -16782,9 +16826,10 @@ var OperationProcessor = class {
       definition.deprecated = true;
     }
     if (explicitSecurity && explicitSecurity.length > 0) {
-      definition.security = explicitSecurity;
+      definition.security = explicitSecurity.map((req) => Object.fromEntries(Object.entries(req).map(([scheme, scopes]) => [this.applyPreset(scheme), scopes])));
     } else if (auth) {
-      const authItems = auth.split(",").map((item) => item.trim());
+      const mapped = performAuthPresetReplacements(auth, this.authPresets);
+      const authItems = mapped.split(",").map((item) => item.trim());
       definition.security = authItems.map((authItem) => ({
         [authItem]: []
       }));
@@ -16997,6 +17042,9 @@ ${suffix}`;
       response.links[link.name] = linkObject;
     }
   }
+  applyPreset(scheme) {
+    return this.authPresets[scheme.toLowerCase()] ?? scheme;
+  }
   createQuerystringParameter(dataTypes) {
     if (!dataTypes.querystringType) {
       return void 0;
@@ -17085,7 +17133,10 @@ var RouteProcessor = class {
       return new RegExp(`^${regexPattern}$`);
     });
     this.responseProcessor = new ResponseProcessor(this.config, this.schemaProcessor);
-    this.operationProcessor = new OperationProcessor(this.schemaProcessor, this.responseProcessor, this.performanceProfile);
+    this.operationProcessor = new OperationProcessor(this.schemaProcessor, this.responseProcessor, {
+      authPresets: this.config.authPresets,
+      performanceProfile: this.performanceProfile
+    });
   }
   processResponsesFromConfig(dataTypes, method) {
     return this.responseProcessor.processResponses(dataTypes, method);