next-openapi-gen 0.8.6 → 0.8.8

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

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

@@ -700,6 +700,16 @@ export class ZodSchemaConverter {
             }
             logger.debug(`[processZodNode] Could not expand factory function '${node.callee.name}' - missing context or not a factory`);
         }
+        // Handle standalone identifier references (e.g., userSchema used directly)
+        if (t.isIdentifier(node)) {
+            const schemaName = node.name;
+            // Try to find and process the referenced schema
+            if (!this.zodSchemas[schemaName]) {
+                this.convertZodSchemaToOpenApi(schemaName);
+            }
+            // Return a reference to the schema
+            return { $ref: `#/components/schemas/${schemaName}` };
+        }
         logger.debug("Unknown Zod schema node:", node);
         return { type: "object" };
     }
@@ -932,6 +942,7 @@ export class ZodSchemaConverter {
                         $ref: `#/components/schemas/${referencedSchemaName}`,
                     };
                     required.push(propName); // Assuming it's required unless marked optional
+                    return; // Skip further processing for this property
                 }
                 // For array of schemas (like z.array(PaymentMethodSchema))
                 if (t.isCallExpression(prop.value) &&
@@ -957,6 +968,7 @@ export class ZodSchemaConverter {
                     if (!isOptional) {
                         required.push(propName);
                     }
+                    return; // Skip further processing for this property
                 }
                 // Process property value (a Zod schema)
                 const propSchema = this.processZodNode(prop.value);

package/package.json

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