next-openapi-gen 0.8.1 → 0.8.3

package/README.md

@@ -4,16 +4,13 @@ Automatically generate OpenAPI 3.0 documentation from Next.js projects, with sup
 
 ## Features
 
-- ✅ Automatic OpenAPI documentation generation from Next.js code
-- ✅ Support for Next.js App Router (including `/api/users/[id]/route.ts` routes)
-- ✅ TypeScript types support
-- ✅ Zod schemas support
-- ✅ Drizzle-Zod support - Generate schemas from Drizzle ORM tables 🆕
-- ✅ JSDoc comments support
-- ✅ Multiple UI interfaces: `Scalar`, `Swagger`, `Redoc`, `Stoplight` and `Rapidoc` available at `/api-docs` url
-- ✅ Path parameters detection (`/users/{id}`)
-- ✅ Intelligent parameter examples
-- ✅ Intuitive CLI for initialization and documentation generation
+- ✅ Automatic OpenAPI 3.0 documentation generation from Next.js App Router
+- ✅ Multiple schema types: `TypeScript`, `Zod`, `Drizzle-Zod`, or `custom YAML/JSON` files 🆕
+- ✅ Mix schema sources simultaneously - perfect for gradual migrations 🆕
+- ✅ JSDoc comments with intelligent parameter examples
+- ✅ Multiple UI interfaces: `Scalar`, `Swagger`, `Redoc`, `Stoplight`, and `RapiDoc` available at `/api-docs` url
+- ✅ Auto-detection of path parameters (e.g., `/users/[id]/route.ts`)
+- ✅ Intuitive CLI for quick setup and generation
 
 ## Supported interfaces
 
@@ -23,6 +20,9 @@ Automatically generate OpenAPI 3.0 documentation from Next.js projects, with sup
 - Stoplight Elements
 - RapiDoc
 
+> [!TIP]
+> You can use the `--ui none` option during initialization to skip UI setup if you only care about generating the OpenAPI documentation.
+
 ## Installation
 
 ```bash
@@ -39,6 +39,9 @@ npx next-openapi-gen init --ui scalar --docs-url api-docs --schema zod
 npx next-openapi-gen generate
 ```
 
+> [!TIP]
+> Use the `--output` option in the `init` command to specify a custom output file for the template. Then you can use the `--template` option in the `generate` command to point to that file.
+
 ## Configuration
 
 During initialization (`npx next-openapi-gen init`), a configuration file `next.openapi.json` will be created in the project's root directory:
@@ -59,7 +62,8 @@ During initialization (`npx next-openapi-gen init`), a configuration file `next.
   ],
   "apiDir": "src/app/api",
   "schemaDir": "src/types", // or "src/schemas" for Zod schemas
-  "schemaType": "zod", // or "typescript" for TypeScript types
+  "schemaType": "zod", // or "typescript", or ["zod", "typescript"] for multiple
+  "schemaFiles": [], // Optional: ["./schemas/models.yaml", "./schemas/api.json"]
   "outputFile": "openapi.json",
   "outputDir": "./public",
   "docsUrl": "/api-docs",
@@ -71,20 +75,21 @@ 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: `"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                                  |
+| Option                 | Description                                                                   |
+| ---------------------- | ----------------------------------------------------------------------------- |
+| `apiDir`               | Path to the API directory                                                     |
+| `schemaDir`            | Path to the types/schemas directory                                           |
+| `schemaType`           | Schema type: `"zod"`, `"typescript"`, or `["zod", "typescript"]` for multiple |
+| `schemaFiles`          | Optional: Array of custom OpenAPI schema files (YAML/JSON) to include         |
+| `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
 
@@ -766,19 +771,61 @@ export const CreatePostSchema = createInsertSchema(posts, {
 
 See the [complete Drizzle-Zod example](./examples/next15-app-drizzle-zod) for a full working implementation with a blog API.
 
+## Multiple Schema Types Support 🆕
+
+Use **multiple schema types simultaneously** in a single project - perfect for gradual migrations, combining hand-written schemas with generated ones (protobuf, GraphQL), or using existing OpenAPI specs.
+
+### Configuration
+
+```json
+{
+  "schemaType": ["zod", "typescript"],
+  "schemaDir": "./src/schemas",
+  "schemaFiles": ["./schemas/external-api.yaml"]
+}
+```
+
+### Schema Resolution Priority
+
+1. **Custom files** (highest) - from `schemaFiles` array
+2. **Zod schemas** (medium) - if `"zod"` in `schemaType`
+3. **TypeScript types** (fallback) - if `"typescript"` in `schemaType`
+
+### Common Use Cases
+
+```json
+// Gradual TypeScript → Zod migration
+{ "schemaType": ["zod", "typescript"] }
+
+// Zod + protobuf schemas
+{
+  "schemaType": ["zod"],
+  "schemaFiles": ["./proto/schemas.yaml"]
+}
+
+// Everything together
+{
+  "schemaType": ["zod", "typescript"],
+  "schemaFiles": ["./openapi-models.yaml"]
+}
+```
+
+Custom schema files support YAML/JSON in OpenAPI 3.0 format. See **[next15-app-mixed-schemas](./examples/next15-app-mixed-schemas)** for a complete working example.
+
 ## Examples
 
 This repository includes several complete example projects:
 
 ### 📦 Available Examples
 
-| Example                                                         | Description                | Features                                        |
-| --------------------------------------------------------------- | -------------------------- | ----------------------------------------------- |
-| **[next15-app-zod](./examples/next15-app-zod)**                 | Zod schemas example        | Users, Products, Orders API with Zod validation |
-| **[next15-app-drizzle-zod](./examples/next15-app-drizzle-zod)** | Drizzle-Zod integration 🆕 | Blog API with Drizzle ORM + drizzle-zod         |
-| **[next15-app-typescript](./examples/next15-app-typescript)**   | TypeScript types           | API with pure TypeScript type definitions       |
-| **[next15-app-scalar](./examples/next15-app-scalar)**           | Scalar UI                  | Modern API documentation interface              |
-| **[next15-app-swagger](./examples/next15-app-swagger)**         | Swagger UI                 | Classic Swagger documentation                   |
+| Example                                                         | Description             | Features                                        |
+| --------------------------------------------------------------- | ----------------------- | ----------------------------------------------- |
+| **[next15-app-zod](./examples/next15-app-zod)**                 | Zod schemas example     | Users, Products, Orders API with Zod validation |
+| **[next15-app-drizzle-zod](./examples/next15-app-drizzle-zod)** | Drizzle-Zod integration | Blog API with Drizzle ORM + drizzle-zod         |
+| **[next15-app-mixed-schemas](./examples/next15-app-mixed-schemas)** 🆕          | Multiple schema types   | Zod + TypeScript + Custom YAML schemas combined |
+| **[next15-app-typescript](./examples/next15-app-typescript)**   | TypeScript types        | API with pure TypeScript type definitions       |
+| **[next15-app-scalar](./examples/next15-app-scalar)**           | Scalar UI               | Modern API documentation interface              |
+| **[next15-app-swagger](./examples/next15-app-swagger)**         | Swagger UI              | Classic Swagger documentation                   |
 
 ### 🚀 Running Examples
 
@@ -824,26 +871,11 @@ Visit `http://localhost:3000/api-docs` to see the generated documentation.
 </table>
 </div>
 
-## Learn More
-
-- **[Drizzle-Zod Example](./examples/next15-app-drizzle-zod)** - Complete example with Drizzle ORM integration
-- **[Drizzle ORM](https://orm.drizzle.team/)** - TypeScript ORM for SQL databases
-- **[drizzle-zod](https://orm.drizzle.team/docs/zod)** - Zod schema generator for Drizzle
-- **[Zod Documentation](https://zod.dev/)** - TypeScript-first schema validation
-- **[Next.js Documentation](https://nextjs.org/docs)** - React framework documentation
-- **[OpenAPI Specification](https://swagger.io/specification/)** - OpenAPI 3.0 spec
-- **[Scalar Documentation](https://docs.scalar.com/)** - Modern API documentation UI
-
 ## Contributing
 
 We welcome contributions! 🎉
 
-Please read our [Contributing Guide](CONTRIBUTING.md) for details on:
-
-- 📝 Commit message guidelines (Conventional Commits)
-- 🔧 Development setup
-- ✅ Pull request process
-- 🚀 Release workflow
+Please read our [Contributing Guide](CONTRIBUTING.md) for details.
 
 ## Changelog
 

package/dist/commands/generate.js

@@ -3,9 +3,12 @@ import fse from "fs-extra";
 import path from "path";
 import ora from "ora";
 import { OpenApiGenerator } from "../lib/openapi-generator.js";
-export async function generate() {
+export async function generate(options) {
+    const { template } = options;
     const spinner = ora("Generating OpenAPI specification...\n").start();
-    const generator = new OpenApiGenerator();
+    const generator = new OpenApiGenerator({
+        templatePath: template,
+    });
     const config = generator.getConfig();
     // Create api dir if not exists
     const apiDir = path.resolve(config.apiDir);

package/dist/commands/init.js

@@ -85,6 +85,9 @@ function getDocsPageDependencies(ui) {
     return deps.join(" ");
 }
 async function createDocsPage(ui, outputFile) {
+    if (ui === "none") {
+        return;
+    }
     const paths = ["app", "api-docs"];
     const srcPath = path.join(process.cwd(), "src");
     if (fs.existsSync(srcPath)) {
@@ -98,6 +101,9 @@ async function createDocsPage(ui, outputFile) {
     spinner.succeed(`Created ${paths.join("/")}/page.tsx for ${ui}.`);
 }
 async function installDependencies(ui) {
+    if (ui === "none") {
+        return;
+    }
     const packageManager = await getPackageManager();
     const installCmd = `${packageManager} ${packageManager === "npm" ? "install" : "add"}`;
     const deps = getDocsPageDependencies(ui);
@@ -111,15 +117,21 @@ function extendOpenApiTemplate(spec, options) {
     spec.docsUrl = options.docsUrl ?? spec.docsUrl;
     spec.schemaType = options.schema ?? spec.schemaType;
 }
+function getOutputPath(output) {
+    if (output) {
+        return path.isAbsolute(output) ? output : path.join(process.cwd(), output);
+    }
+    return path.join(process.cwd(), "next.openapi.json");
+}
 export async function init(options) {
-    const { ui } = options;
+    const { ui, output } = options;
     spinner.start();
     try {
-        const outputPath = path.join(process.cwd(), "next.openapi.json");
+        const outputPath = getOutputPath(output);
         const template = { ...openapiTemplate };
         extendOpenApiTemplate(template, options);
         await fse.writeJson(outputPath, template, { spaces: 2 });
-        spinner.succeed(`Created OpenAPI template in next.openapi.json`);
+        spinner.succeed(`Created OpenAPI template in ${outputPath}`);
         createDocsPage(ui, template.outputFile);
         installDependencies(ui);
     }

package/dist/index.js

@@ -9,17 +9,19 @@ program
     .description("Super fast and easy way to generate OpenAPI documentation for Next.js");
 program
     .command("init")
-    .addOption(new Option("-i, --ui <type>", "Specify the UI type, e.g., scalar")
-    .choices(["scalar", "swagger", "redoc", "stoplight", "rapidoc"])
+    .addOption(new Option("-i, --ui <type>", "Specify the UI type, e.g., scalar. Use \"none\" for no UI")
+    .choices(["scalar", "swagger", "redoc", "stoplight", "rapidoc", "none"])
     .default("swagger"))
     .option("-u, --docs-url <url>", "Specify the docs URL", "api-docs")
     .addOption(new Option("-s, --schema <schemaType>", "Specify the schema tool")
     .choices(["zod", "typescript"])
     .default("zod"))
+    .option("-o, --output <file>", "Specify the output path for the OpenAPI template.", "next.openapi.json")
     .description("Initialize a openapi specification")
     .action(init);
 program
     .command("generate")
     .description("Generate a specification based on api routes")
+    .option("-t, --template <file>", "Specify the OpenAPI template file", "next.openapi.json")
     .action(generate);
 program.parse(process.argv);

package/dist/lib/openapi-generator.js

@@ -7,8 +7,8 @@ export class OpenApiGenerator {
     config;
     template;
     routeProcessor;
-    constructor() {
-        const templatePath = path.resolve("./next.openapi.json");
+    constructor(opts = {}) {
+        const templatePath = opts.templatePath || path.resolve("./next.openapi.json");
         this.template = JSON.parse(fs.readFileSync(templatePath, "utf-8"));
         this.config = this.getConfig();
         this.routeProcessor = new RouteProcessor(this.config);
@@ -17,7 +17,7 @@ export class OpenApiGenerator {
     }
     getConfig() {
         // @ts-ignore
-        const { apiDir, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, ignoreRoutes, schemaType = "typescript", defaultResponseSet, responseSets, errorConfig, debug } = this.template;
+        const { apiDir, schemaDir, docsUrl, ui, outputFile, outputDir, includeOpenApiRoutes, ignoreRoutes, schemaType = "typescript", schemaFiles, defaultResponseSet, responseSets, errorConfig, debug } = this.template;
         return {
             apiDir: apiDir || "./src/app/api",
             schemaDir: schemaDir || "./src",
@@ -28,6 +28,7 @@ export class OpenApiGenerator {
             includeOpenApiRoutes: includeOpenApiRoutes || false,
             ignoreRoutes: ignoreRoutes || [],
             schemaType,
+            schemaFiles: schemaFiles || [],
             defaultResponseSet,
             responseSets,
             errorConfig,

package/dist/lib/route-processor.js

@@ -18,7 +18,7 @@ export class RouteProcessor {
     processFileTracker = {};
     constructor(config) {
         this.config = config;
-        this.schemaProcessor = new SchemaProcessor(config.schemaDir, config.schemaType);
+        this.schemaProcessor = new SchemaProcessor(config.schemaDir, config.schemaType, config.schemaFiles);
     }
     buildResponsesFromConfig(dataTypes, method) {
         const responses = {};

package/dist/lib/schema-processor.js

@@ -2,50 +2,107 @@ import fs from "fs";
 import path from "path";
 import traverseModule from "@babel/traverse";
 import * as t from "@babel/types";
+import yaml from "js-yaml";
 // 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";
+/**
+ * Normalize schemaType to array
+ */
+function normalizeSchemaTypes(schemaType) {
+    return Array.isArray(schemaType) ? schemaType : [schemaType];
+}
 export class SchemaProcessor {
     schemaDir;
     typeDefinitions = {};
     openapiDefinitions = {};
     contentType = "";
+    customSchemas = {};
     directoryCache = {};
     statCache = {};
     processSchemaTracker = {};
     processingTypes = new Set();
-    zodSchemaConverter;
-    schemaType;
+    zodSchemaConverter = null;
+    schemaTypes;
     isResolvingPickOmitBase = false;
-    constructor(schemaDir, schemaType = "typescript") {
+    constructor(schemaDir, schemaType = "typescript", schemaFiles) {
         this.schemaDir = path.resolve(schemaDir);
-        this.schemaType = schemaType;
-        if (schemaType === "zod") {
+        this.schemaTypes = normalizeSchemaTypes(schemaType);
+        // Initialize Zod converter if Zod is enabled
+        if (this.schemaTypes.includes("zod")) {
             this.zodSchemaConverter = new ZodSchemaConverter(schemaDir);
         }
+        // Load custom schema files if provided
+        if (schemaFiles && schemaFiles.length > 0) {
+            this.loadCustomSchemas(schemaFiles);
+        }
+    }
+    /**
+     * Load custom OpenAPI schema files (YAML/JSON)
+     */
+    loadCustomSchemas(schemaFiles) {
+        for (const filePath of schemaFiles) {
+            try {
+                const resolvedPath = path.resolve(filePath);
+                if (!fs.existsSync(resolvedPath)) {
+                    logger.warn(`Schema file not found: ${filePath}`);
+                    continue;
+                }
+                const content = fs.readFileSync(resolvedPath, "utf-8");
+                const ext = path.extname(filePath).toLowerCase();
+                let parsed;
+                if (ext === ".yaml" || ext === ".yml") {
+                    parsed = yaml.load(content);
+                }
+                else if (ext === ".json") {
+                    parsed = JSON.parse(content);
+                }
+                else {
+                    logger.warn(`Unsupported file type: ${filePath} (use .json, .yaml, or .yml)`);
+                    continue;
+                }
+                // Extract schemas from OpenAPI structure or use file content directly
+                const schemas = parsed?.components?.schemas || parsed?.schemas || parsed;
+                if (typeof schemas === "object" && schemas !== null) {
+                    Object.assign(this.customSchemas, schemas);
+                    logger.log(`✓ Loaded custom schemas from: ${filePath}`);
+                }
+                else {
+                    logger.warn(`No valid schemas found in ${filePath}. Expected OpenAPI format with components.schemas or plain object.`);
+                }
+            }
+            catch (error) {
+                logger.warn(`Failed to load schema file ${filePath}: ${error.message}`);
+            }
+        }
     }
     /**
      * Get all defined schemas (for components.schemas section)
+     * Merges schemas from all sources with proper priority:
+     * 1. TypeScript types (lowest priority - base layer)
+     * 2. Zod schemas (medium priority)
+     * 3. Custom files (highest priority - overrides all)
      */
     getDefinedSchemas() {
-        // Filter out generic type parameters and invalid schema names
+        const merged = {};
+        // Layer 1: TypeScript types (base layer)
         const filteredSchemas = {};
         Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
             if (!this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key)) {
                 filteredSchemas[key] = value;
             }
         });
-        // If using Zod, also include all processed Zod schemas
-        if (this.schemaType === "zod" && this.zodSchemaConverter) {
+        Object.assign(merged, filteredSchemas);
+        // Layer 2: Zod schemas (if enabled - overrides TypeScript)
+        if (this.schemaTypes.includes("zod") && this.zodSchemaConverter) {
             const zodSchemas = this.zodSchemaConverter.getProcessedSchemas();
-            return {
-                ...filteredSchemas,
-                ...zodSchemas,
-            };
+            Object.assign(merged, zodSchemas);
         }
-        return filteredSchemas;
+        // Layer 3: Custom files (highest priority - overrides all)
+        Object.assign(merged, this.customSchemas);
+        return merged;
     }
     findSchemaDefinition(schemaName, contentType) {
         let schemaNode = null;
@@ -55,8 +112,13 @@ export class SchemaProcessor {
         if (schemaName.includes("<") && schemaName.includes(">")) {
             return this.resolveGenericTypeFromString(schemaName);
         }
-        // Check if we should use Zod schemas
-        if (this.schemaType === "zod") {
+        // Priority 1: Check custom schemas first (highest priority)
+        if (this.customSchemas[schemaName]) {
+            logger.debug(`Found schema in custom files: ${schemaName}`);
+            return this.customSchemas[schemaName];
+        }
+        // Priority 2: Try Zod schemas if enabled
+        if (this.schemaTypes.includes("zod") && this.zodSchemaConverter) {
             logger.debug(`Looking for Zod schema: ${schemaName}`);
             // Check type mapping first
             const mappedSchemaName = this.zodSchemaConverter.typeToSchemaMapping[schemaName];
@@ -160,7 +222,8 @@ export class SchemaProcessor {
         this.processingTypes.add(typeName);
         try {
             // If we are using Zod and the given type is not found yet, try using Zod converter first
-            if (this.schemaType === "zod" && !this.openapiDefinitions[typeName]) {
+            if (this.schemaTypes.includes("zod") &&
+                !this.openapiDefinitions[typeName]) {
                 const zodSchema = this.zodSchemaConverter.convertZodSchemaToOpenApi(typeName);
                 if (zodSchema) {
                     this.openapiDefinitions[typeName] = zodSchema;
@@ -182,7 +245,7 @@ export class SchemaProcessor {
                 t.isMemberExpression(typeNode.callee) &&
                 t.isIdentifier(typeNode.callee.object) &&
                 typeNode.callee.object.name === "z") {
-                if (this.schemaType === "zod") {
+                if (this.schemaTypes.includes("zod")) {
                     const zodSchema = this.zodSchemaConverter.processZodNode(typeNode);
                     if (zodSchema) {
                         this.openapiDefinitions[typeName] = zodSchema;
@@ -784,7 +847,7 @@ export class SchemaProcessor {
             this.findSchemaDefinition(responseType, "response");
             responses = this.openapiDefinitions[responseType] || {};
         }
-        if (this.schemaType === "zod") {
+        if (this.schemaTypes.includes("zod")) {
             const schemasToProcess = [
                 paramsType,
                 pathParamsType,

package/dist/openapi-template.js

@@ -87,7 +87,8 @@ export default {
     },
     apiDir: "./src/app/api",
     schemaDir: "./src",
-    schemaType: "zod", // or "typescript"
+    schemaType: "zod", // or "typescript" or ["zod", "typescript"]
+    schemaFiles: [], // Optional: ["./openapi-models.yaml", "./schemas.json"]
     docsUrl: "api-docs",
     ui: "scalar",
     outputFile: "openapi.json",

package/dist/types.js

@@ -1,2 +1 @@
 export {};
-// Test feature

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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",
@@ -55,9 +55,11 @@
     "@babel/types": "^7.28.2",
     "commander": "^14.0.0",
     "fs-extra": "^11.3.1",
+    "js-yaml": "^4.1.0",
     "ora": "^8.2.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.3.0",
     "@vitest/ui": "^3.2.4",
     "conventional-changelog-cli": "^5.0.0",