next-openapi-gen 0.8.8 → 0.9.0

package/README.md

@@ -14,15 +14,12 @@ Automatically generate OpenAPI 3.0 documentation from Next.js projects, with sup
 
 ## Supported interfaces
 
-- Scalar 🆕
+- Scalar 💡(default)
 - Swagger
 - Redoc
 - 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
@@ -33,14 +30,27 @@ npm install next-openapi-gen --save-dev
 
 ```bash
 # Initialize OpenAPI configuration
-npx next-openapi-gen init --ui scalar --docs-url api-docs --schema zod
+npx next-openapi-gen init
 
 # Generate OpenAPI documentation
 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.
+> Scalar UI and Zod are set by default
+
+
+### Init Command Options
+
+| Option | Choices | Default | Description |
+|--------|---------|---------|-------------|
+| `--ui` | `scalar`, `swagger`, `redoc`, `stoplight`, `rapidoc`, `none` | `scalar` | UI framework for API docs |
+| `--schema` | `zod`, `typescript` | `zod` | Schema validation tool |
+| `--docs-url` | any string | `api-docs` | URL path for documentation page |
+| `--output` | any path | `next.openapi.json` | Output file for OpenAPI template |
+
+> [!TIP]
+> Use `--ui none` to skip UI setup and only generate the OpenAPI specification file.
 
 ## Configuration
 
@@ -784,6 +794,51 @@ Factory functions work with any naming convention and support:
 - Imported schemas
 - Multiple factory patterns in the same project
 
+### Schema Composition with `.extend()`
+
+Zod's `.extend()` method allows you to build upon existing schemas:
+
+```typescript
+// src/schemas/user.ts
+
+// Base user schema
+export const BaseUserSchema = z.object({
+  id: z.string().uuid().describe("User ID"),
+  email: z.string().email().describe("Email address"),
+});
+
+// Extend with additional fields
+export const UserProfileSchema = BaseUserSchema.extend({
+  name: z.string().describe("Full name"),
+  bio: z.string().optional().describe("User biography"),
+});
+
+// Multiple levels of extension
+export const AdminUserSchema = UserProfileSchema.extend({
+  role: z.enum(["admin", "moderator"]).describe("Admin role"),
+  permissions: z.array(z.string()).describe("Permission list"),
+});
+
+export const UserIdParams = z.object({
+  id: z.string().uuid().describe("User ID"),
+});
+
+// src/app/api/users/[id]/route.ts
+
+/**
+ * Get user profile
+ * @pathParams UserIdParams
+ * @response UserProfileSchema
+ * @openapi
+ */
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  // Returns: { id, email, name, bio? }
+}
+```
+
 ### Drizzle-Zod Support
 
 The library fully supports **drizzle-zod** for generating Zod schemas from Drizzle ORM table definitions. This provides a single source of truth for your database schema, validation, and API documentation.

package/dist/commands/init.js

@@ -5,13 +5,23 @@ import ora from "ora";
 import { exec } from "child_process";
 import util from "util";
 import openapiTemplate from "../openapi-template.js";
-import { scalarDeps, ScalarUI } from "../components/scalar.js";
-import { swaggerDeps, SwaggerUI } from "../components/swagger.js";
-import { redocDeps, RedocUI } from "../components/redoc.js";
-import { stoplightDeps, StoplightUI } from "../components/stoplight.js";
-import { rapidocDeps, RapidocUI } from "../components/rapidoc.js";
+import { scalarDeps, scalarDevDeps, ScalarUI } from "../components/scalar.js";
+import { swaggerDeps, swaggerDevDeps, SwaggerUI } from "../components/swagger.js";
+import { redocDeps, redocDevDeps, RedocUI } from "../components/redoc.js";
+import { stoplightDeps, stoplightDevDeps, StoplightUI } from "../components/stoplight.js";
+import { rapidocDeps, rapidocDevDeps, RapidocUI } from "../components/rapidoc.js";
 const execPromise = util.promisify(exec);
 const spinner = ora("Initializing project with OpenAPI template...\n");
+async function hasDependency(packageName) {
+    try {
+        const packageJsonPath = path.join(process.cwd(), "package.json");
+        const packageJson = await fse.readJson(packageJsonPath);
+        return !!(packageJson.dependencies?.[packageName] || packageJson.devDependencies?.[packageName]);
+    }
+    catch {
+        return false;
+    }
+}
 const getPackageManager = async () => {
     let currentDir = process.cwd();
     while (true) {
@@ -84,6 +94,25 @@ function getDocsPageDependencies(ui) {
     }
     return deps.join(" ");
 }
+function getDocsPageDevDependencies(ui) {
+    let devDeps = [];
+    if (ui === "scalar") {
+        devDeps = scalarDevDeps;
+    }
+    else if (ui === "swagger") {
+        devDeps = swaggerDevDeps;
+    }
+    else if (ui === "redoc") {
+        devDeps = redocDevDeps;
+    }
+    else if (ui === "stoplight") {
+        devDeps = stoplightDevDeps;
+    }
+    else if (ui === "rapidoc") {
+        devDeps = rapidocDevDeps;
+    }
+    return devDeps.join(" ");
+}
 async function createDocsPage(ui, outputFile) {
     if (ui === "none") {
         return;
@@ -100,17 +129,41 @@ async function createDocsPage(ui, outputFile) {
     await fs.promises.writeFile(componentPath, docsPage.trim());
     spinner.succeed(`Created ${paths.join("/")}/page.tsx for ${ui}.`);
 }
-async function installDependencies(ui) {
-    if (ui === "none") {
-        return;
-    }
+async function installDependencies(ui, schema) {
     const packageManager = await getPackageManager();
     const installCmd = `${packageManager} ${packageManager === "npm" ? "install" : "add"}`;
-    const deps = getDocsPageDependencies(ui);
-    const flags = getDocsPageInstallFlags(ui, packageManager);
-    spinner.succeed(`Installing ${deps} dependencies...`);
-    const resp = await execPromise(`${installCmd} ${deps} ${flags}`);
-    spinner.succeed(`Successfully installed ${deps}.`);
+    // Install UI dependencies
+    if (ui !== "none") {
+        const deps = getDocsPageDependencies(ui);
+        const devDeps = getDocsPageDevDependencies(ui);
+        const flags = getDocsPageInstallFlags(ui, packageManager);
+        if (deps) {
+            spinner.succeed(`Installing ${deps} dependencies...`);
+            await execPromise(`${installCmd} ${deps} ${flags}`);
+            spinner.succeed(`Successfully installed ${deps}.`);
+        }
+        if (devDeps) {
+            const devFlag = packageManager === "npm" ? "--save-dev" : "-D";
+            spinner.succeed(`Installing ${devDeps} dev dependencies...`);
+            await execPromise(`${installCmd} ${devFlag} ${devDeps} ${flags}`);
+            spinner.succeed(`Successfully installed ${devDeps}.`);
+        }
+    }
+    // Install schema dependencies
+    const schemaTypes = Array.isArray(schema) ? schema : [schema];
+    for (const schemaType of schemaTypes) {
+        if (schemaType === "zod" && !(await hasDependency("zod"))) {
+            spinner.succeed(`Installing zod...`);
+            await execPromise(`${installCmd} zod`);
+            spinner.succeed(`Successfully installed zod.`);
+        }
+        else if (schemaType === "typescript" && !(await hasDependency("typescript"))) {
+            const devFlag = packageManager === "npm" ? "--save-dev" : "-D";
+            spinner.succeed(`Installing typescript...`);
+            await execPromise(`${installCmd} ${devFlag} typescript`);
+            spinner.succeed(`Successfully installed typescript.`);
+        }
+    }
 }
 function extendOpenApiTemplate(spec, options) {
     spec.ui = options.ui ?? spec.ui;
@@ -124,7 +177,7 @@ function getOutputPath(output) {
     return path.join(process.cwd(), "next.openapi.json");
 }
 export async function init(options) {
-    const { ui, output } = options;
+    const { ui, output, schema } = options;
     spinner.start();
     try {
         const outputPath = getOutputPath(output);
@@ -133,7 +186,7 @@ export async function init(options) {
         await fse.writeJson(outputPath, template, { spaces: 2 });
         spinner.succeed(`Created OpenAPI template in ${outputPath}`);
         createDocsPage(ui, template.outputFile);
-        installDependencies(ui);
+        installDependencies(ui, schema);
     }
     catch (error) {
         spinner.fail(`Failed to initialize project: ${error.message}`);

package/dist/components/rapidoc.js

@@ -1,4 +1,5 @@
 export const rapidocDeps = ["rapidoc"];
+export const rapidocDevDeps = [];
 export function RapidocUI(outputFile) {
     return `
 "use client";

package/dist/components/redoc.js

@@ -1,4 +1,5 @@
 export const redocDeps = ["redoc"];
+export const redocDevDeps = [];
 export function RedocUI(outputFile) {
     return `
 "use client";

package/dist/components/scalar.js

@@ -1,4 +1,5 @@
 export const scalarDeps = ["@scalar/api-reference-react", "ajv"];
+export const scalarDevDeps = [];
 export function ScalarUI(outputFile) {
     return `
 "use client";

package/dist/components/stoplight.js

@@ -1,4 +1,5 @@
 export const stoplightDeps = ["@stoplight/elements"];
+export const stoplightDevDeps = [];
 export function StoplightUI(outputFile) {
     return `
 "use client";

package/dist/components/swagger.js

@@ -1,4 +1,5 @@
 export const swaggerDeps = ["swagger-ui", "swagger-ui-react"];
+export const swaggerDevDeps = ["@types/swagger-ui-react"];
 export function SwaggerUI(outputFile) {
     return `
 import "swagger-ui-react/swagger-ui.css";
@@ -6,7 +7,6 @@ import "swagger-ui-react/swagger-ui.css";
 import dynamic from "next/dynamic";
 
 const SwaggerUI = dynamic(() => import("swagger-ui-react"), {
-  ssr: false,
   loading: () => <p>Loading Component...</p>,
 });
 

package/dist/index.js

@@ -11,7 +11,7 @@ program
     .command("init")
     .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"))
+    .default("scalar"))
     .option("-u, --docs-url <url>", "Specify the docs URL", "api-docs")
     .addOption(new Option("-s, --schema <schemaType>", "Specify the schema tool")
     .choices(["zod", "typescript"])

package/dist/lib/zod-converter.js

@@ -400,6 +400,54 @@ export class ZodSchemaConverter {
                                         });
                                     }
                                     break;
+                                case "extend":
+                                    // Extend the schema with new properties
+                                    if (node.arguments.length > 0 &&
+                                        t.isObjectExpression(node.arguments[0])) {
+                                        const extensionProperties = {};
+                                        const extensionRequired = [];
+                                        node.arguments[0].properties.forEach((prop) => {
+                                            if (t.isObjectProperty(prop)) {
+                                                const key = t.isIdentifier(prop.key)
+                                                    ? prop.key.name
+                                                    : t.isStringLiteral(prop.key)
+                                                        ? prop.key.value
+                                                        : null;
+                                                if (key) {
+                                                    // Process the Zod type for this property
+                                                    const propSchema = this.processZodNode(prop.value);
+                                                    if (propSchema) {
+                                                        extensionProperties[key] = propSchema;
+                                                        // Check if the schema itself has nullable set (which processZodNode sets for optional fields)
+                                                        const isOptional = propSchema.nullable === true;
+                                                        if (!isOptional) {
+                                                            extensionRequired.push(key);
+                                                        }
+                                                    }
+                                                }
+                                            }
+                                        });
+                                        // Merge with existing schema
+                                        if (schema.properties) {
+                                            schema.properties = {
+                                                ...schema.properties,
+                                                ...extensionProperties,
+                                            };
+                                        }
+                                        else {
+                                            schema.properties = extensionProperties;
+                                        }
+                                        // Merge required arrays
+                                        if (extensionRequired.length > 0) {
+                                            schema.required = [
+                                                ...(schema.required || []),
+                                                ...extensionRequired,
+                                            ];
+                                            // Deduplicate
+                                            schema.required = [...new Set(schema.required)];
+                                        }
+                                    }
+                                    break;
                             }
                             return schema;
                         };
@@ -989,8 +1037,9 @@ export class ZodSchemaConverter {
             properties,
         };
         if (required.length > 0) {
+            // Deduplicate required array using Set
             // @ts-ignore
-            schema.required = required;
+            schema.required = [...new Set(required)];
         }
         return schema;
     }
@@ -1371,7 +1420,24 @@ export class ZodSchemaConverter {
                 if (node.arguments.length > 0 &&
                     t.isObjectExpression(node.arguments[0])) {
                     // Get the base schema by processing the object that extend is called on
-                    const baseSchema = this.processZodNode(node.callee.object);
+                    const baseSchemaResult = this.processZodNode(node.callee.object);
+                    // If it's a reference, resolve it to the actual schema
+                    let baseSchema = baseSchemaResult;
+                    if (baseSchemaResult && baseSchemaResult.$ref) {
+                        const schemaName = baseSchemaResult.$ref.replace("#/components/schemas/", "");
+                        // Try to convert the base schema if not already processed
+                        if (!this.zodSchemas[schemaName]) {
+                            logger.debug(`[extend] Base schema ${schemaName} not found, attempting to convert it`);
+                            this.convertZodSchemaToOpenApi(schemaName);
+                        }
+                        // Now retrieve the converted schema
+                        if (this.zodSchemas[schemaName]) {
+                            baseSchema = this.zodSchemas[schemaName];
+                        }
+                        else {
+                            logger.debug(`Could not resolve reference for extend: ${schemaName}`);
+                        }
+                    }
                     // Process the extension object
                     const extendNode = {
                         type: "CallExpression",

package/package.json

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