feat: add support for custom @operationid JSDoc tag (#60)

Author: tazo90

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

examples/next15-app-zod/public/openapi.json

@@ -1666,7 +1666,7 @@
   "paths": {
     "/orders": {
       "get": {
-        "operationId": "get-orders",
+        "operationId": "getOrdersList",
         "summary": "Get orders list\r",
         "description": "Retrieves a paginated list of orders with filtering and sorting options",
         "tags": [
@@ -1764,7 +1764,7 @@
         }
       },
       "post": {
-        "operationId": "post-orders",
+        "operationId": "createOrder",
         "summary": "Create order\r",
         "description": "Creates a new order from cart",
         "tags": [

examples/next15-app-zod/src/app/api/orders/route.ts

@@ -3,6 +3,7 @@ import { NextRequest, NextResponse } from "next/server";
 /**
  * Get orders list
  * @description Retrieves a paginated list of orders with filtering and sorting options
+ * @operationId getOrdersList
  * @params OrdersQueryParams
  * @response OrdersResponse
  * @auth bearer
@@ -17,6 +18,7 @@ export async function GET(request: NextRequest) {
 /**
  * Create order
  * @description Creates a new order from cart
+ * @operationId createOrder
  * @body CreateOrderBody
  * @response OrderSchema
  * @auth bearer

src/lib/route-processor.ts

@@ -323,7 +323,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,

src/lib/utils.ts

@@ -43,6 +43,7 @@ export function extractJSDocComments(path: NodePath): DataTypes {
   let responseSet = "";
   let addResponses = "";
   let successCode = "";
+  let operationId = "";
 
   if (comments) {
     comments.forEach((comment) => {
@@ -152,6 +153,14 @@ export function extractJSDocComments(path: NodePath): DataTypes {
         }
       }
 
+      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(
@@ -186,6 +195,7 @@ export function extractJSDocComments(path: NodePath): DataTypes {
     responseSet,
     addResponses,
     successCode,
+    operationId,
   };
 }
 

src/types.ts

@@ -163,6 +163,7 @@ export type DataTypes = {
   responseSet?: string; // e.g. "authErrors" or "publicErrors,crudErrors"
   addResponses?: string; // e.g. "409:ConflictResponse,429:RateLimitResponse"
   successCode?: string; // e.g "201" for POST
+  operationId?: string; // Custom operation ID (overrides auto-generated)
 };
 
 export type RouteConfig = {

tests/utils.test.ts

@@ -204,3 +204,124 @@ describe('extractJSDocComments - @ignore tag', () => {
     expect(dataTypes?.deprecated).toBe(true);
   });
 });
+
+describe('extractJSDocComments - @operationId tag', () => {
+  it('should extract @operationId from JSDoc comment', () => {
+    const code = `
+      /**
+       * Get user by ID
+       * @operationId getUserById
+       * @response UserResponse
+       */
+      export async function GET() {}
+    `;
+
+    const ast = parseTypeScriptFile(code);
+    let dataTypes;
+
+    traverse(ast, {
+      ExportNamedDeclaration: (path) => {
+        dataTypes = extractJSDocComments(path);
+      },
+    });
+
+    expect(dataTypes).toBeDefined();
+    expect(dataTypes?.operationId).toBe('getUserById');
+    expect(dataTypes?.responseType).toBe('UserResponse');
+  });
+
+  it('should return empty operationId when not specified', () => {
+    const code = `
+      /**
+       * Get user by ID
+       * @response UserResponse
+       */
+      export async function GET() {}
+    `;
+
+    const ast = parseTypeScriptFile(code);
+    let dataTypes;
+
+    traverse(ast, {
+      ExportNamedDeclaration: (path) => {
+        dataTypes = extractJSDocComments(path);
+      },
+    });
+
+    expect(dataTypes).toBeDefined();
+    expect(dataTypes?.operationId).toBe('');
+    expect(dataTypes?.responseType).toBe('UserResponse');
+  });
+
+  it('should handle @operationId with underscores and numbers', () => {
+    const code = `
+      /**
+       * @operationId create_user_v2
+       */
+      export async function POST() {}
+    `;
+
+    const ast = parseTypeScriptFile(code);
+    let dataTypes;
+
+    traverse(ast, {
+      ExportNamedDeclaration: (path) => {
+        dataTypes = extractJSDocComments(path);
+      },
+    });
+
+    expect(dataTypes?.operationId).toBe('create_user_v2');
+  });
+
+  it('should extract @operationId alongside other tags', () => {
+    const code = `
+      /**
+       * Create new user
+       * @description Creates a new user in the system
+       * @operationId createNewUser
+       * @body CreateUserBody
+       * @response 201:UserResponse
+       * @auth bearer
+       * @tag Users
+       */
+      export async function POST() {}
+    `;
+
+    const ast = parseTypeScriptFile(code);
+    let dataTypes;
+
+    traverse(ast, {
+      ExportNamedDeclaration: (path) => {
+        dataTypes = extractJSDocComments(path);
+      },
+    });
+
+    expect(dataTypes?.operationId).toBe('createNewUser');
+    expect(dataTypes?.description).toBe('Creates a new user in the system');
+    expect(dataTypes?.bodyType).toBe('CreateUserBody');
+    expect(dataTypes?.successCode).toBe('201');
+    expect(dataTypes?.responseType).toBe('UserResponse');
+    expect(dataTypes?.auth).toBe('BearerAuth');
+    expect(dataTypes?.tag).toBe('Users');
+  });
+
+  it('should handle camelCase operationId', () => {
+    const code = `
+      /**
+       * @operationId listAllUsersWithFilters
+       */
+      export async function GET() {}
+    `;
+
+    const ast = parseTypeScriptFile(code);
+    let dataTypes;
+
+    traverse(ast, {
+      ExportNamedDeclaration: (path) => {
+        dataTypes = extractJSDocComments(path);
+      },
+    });
+
+    expect(dataTypes?.operationId).toBe('listAllUsersWithFilters');
+  });
+});