next-openapi-gen 0.8.7 → 0.8.9

package/README.md

@@ -201,6 +201,7 @@ export async function POST(request: NextRequest) {
 | Tag                    | Description                                                                                                              |
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
 | `@description`         | Endpoint description                                                                                                     |
+| `@operationId`         | Custom operation ID (overrides auto-generated ID)                                                                        |
 | `@pathParams`          | Path parameters type/schema                                                                                              |
 | `@params`              | Query parameters type/schema                                                                                             |
 | `@body`                | Request body type/schema                                                                                                 |
@@ -424,6 +425,23 @@ export async function GET() {
 }
 ```
 
+### Custom Operation ID
+
+```typescript
+// src/app/api/users/[id]/route.ts
+
+/**
+ * Get user by ID
+ * @operationId getUserById
+ * @pathParams UserParams
+ * @response UserResponse
+ */
+export async function GET() {
+  // ...
+}
+// Generates: operationId: "getUserById" instead of auto-generated "get-users-{id}"
+```
+
 ### File Uploads / Multipart Form Data
 
 ```typescript
@@ -766,6 +784,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/lib/route-processor.js

@@ -248,7 +248,7 @@ export class RouteProcessor {
         const method = varName.toLowerCase();
         const routePath = this.getRoutePath(filePath);
         const rootPath = capitalize(routePath.split("/")[1]);
-        const operationId = getOperationId(routePath, method);
+        const operationId = dataTypes.operationId || getOperationId(routePath, method);
         const { tag, summary, description, auth, isOpenApi, deprecated, bodyDescription, responseDescription, } = dataTypes;
         if (this.config.includeOpenApiRoutes && !isOpenApi) {
             // If flag is enabled and there is no @openapi tag, then skip path

package/dist/lib/utils.js

@@ -34,6 +34,7 @@ export function extractJSDocComments(path) {
     let responseSet = "";
     let addResponses = "";
     let successCode = "";
+    let operationId = "";
     if (comments) {
         comments.forEach((comment) => {
             const commentValue = cleanComment(comment.value);
@@ -124,6 +125,13 @@ export function extractJSDocComments(path) {
                     addResponses = match[1].trim();
                 }
             }
+            if (commentValue.includes("@operationId")) {
+                const regex = /@operationId\s+(\S+)/;
+                const match = commentValue.match(regex);
+                if (match && match[1]) {
+                    operationId = match[1].trim();
+                }
+            }
             if (commentValue.includes("@response")) {
                 // Updated regex to support generic types
                 const responseMatch = commentValue.match(/@response\s+(?:(\d+):)?([^@\n\r]+)(?:\s+(.*))?/);
@@ -156,6 +164,7 @@ export function extractJSDocComments(path) {
         responseSet,
         addResponses,
         successCode,
+        operationId,
     };
 }
 export function extractTypeFromComment(commentValue, tag) {

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.7",
+  "version": "0.8.9",
   "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",