feat: Set operationId in open-api docs

Author: netiperher

.changeset/red-seals-fry.md

@@ -0,0 +1,5 @@
+---
+'@ts-rest/open-api': minor
+---
+
+Allow setting operationId in open-api docs

libs/ts-rest/open-api/src/lib/ts-rest-open-api.spec.ts

@@ -125,12 +125,69 @@ const expectedApiDoc = {
 
 describe('ts-rest-open-api', () => {
   describe('generateOpenApi', () => {
-    it('w/ no parameters', async () => {
+    it('should generate doc with defaults', async () => {
       const apiDoc = generateOpenApi(router, {
         info: { title: 'Blog API', version: '0.1' },
       });
 
-      expect(apiDoc).toEqual(expectedApiDoc);
+      expect(apiDoc).toStrictEqual(expectedApiDoc);
+    });
+
+    it('should generate doc with operation ids', async () => {
+      const apiDoc = generateOpenApi(
+        router,
+        {
+          info: { title: 'Blog API', version: '0.1' },
+        },
+        { setOperationId: true }
+      );
+
+      expect(apiDoc).toEqual({
+        ...expectedApiDoc,
+        paths: {
+          '/health': {
+            get: {
+              ...expectedApiDoc.paths['/health'].get,
+              operationId: 'health',
+            },
+          },
+          '/posts': {
+            post: {
+              ...expectedApiDoc.paths['/posts'].post,
+              operationId: 'createPost',
+            },
+          },
+          '/posts/{id}': {
+            get: {
+              ...expectedApiDoc.paths['/posts/{id}'].get,
+              operationId: 'getPost',
+            },
+          },
+        },
+      });
+    });
+
+    it('should throw when duplicate operationIds', async () => {
+      const router = c.router({
+        posts: postsRouter,
+        getPost: {
+          method: 'GET',
+          path: `/posts/:id`,
+          responses: {
+            200: c.response<Post | null>(),
+          },
+        },
+      });
+
+      expect(() =>
+        generateOpenApi(
+          router,
+          {
+            info: { title: 'Blog API', version: '0.1' },
+          },
+          { setOperationId: true }
+        )
+      ).toThrowError(/getPost/);
     });
   });
 });

libs/ts-rest/open-api/src/lib/ts-rest-open-api.ts

@@ -11,8 +11,13 @@ import zodToJsonSchema from 'zod-to-json-schema';
 const getPathsFromRouter = (
   router: AppRouter,
   pathHistory?: string[]
-): { path: string; route: AppRoute; paths: string[] }[] => {
-  const paths: { path: string; route: AppRoute; paths: string[] }[] = [];
+): { id: string; path: string; route: AppRoute; paths: string[] }[] => {
+  const paths: {
+    id: string;
+    path: string;
+    route: AppRoute;
+    paths: string[];
+  }[] = [];
 
   Object.keys(router).forEach((key) => {
     const value = router[key];
@@ -22,6 +27,7 @@ const getPathsFromRouter = (
       const pathWithPathParams = value.path.replace(/:(\w+)/g, '{$1}');
 
       paths.push({
+        id: key,
         path: pathWithPathParams,
         route: value,
         paths: pathHistory ?? [],
@@ -54,7 +60,8 @@ const getResponseSchemaFromZod = (response: unknown) => {
 
 export const generateOpenApi = (
   router: AppRouter,
-  options: Omit<OpenAPIObject, 'paths' | 'openapi'> & { info: InfoObject }
+  apiDoc: Omit<OpenAPIObject, 'paths' | 'openapi'> & { info: InfoObject },
+  options: { setOperationId?: boolean } = {}
 ): OpenAPIObject => {
   const paths = getPathsFromRouter(router);
 
@@ -66,7 +73,19 @@ export const generateOpenApi = (
     PATCH: 'patch',
   };
 
+  const operationIds = new Map<string, string[]>();
+
   const pathObject = paths.reduce((acc, path) => {
+    if (options.setOperationId) {
+      const existingOp = operationIds.get(path.id);
+      if (existingOp) {
+        throw new Error(
+          `Route '${path.id}' already defined under ${existingOp.join('.')}`
+        );
+      }
+      operationIds.set(path.id, path.paths);
+    }
+
     const paramsFromPath = path.path
       .match(/{[^}]+}/g)
       ?.map((param) => param.slice(1, -1));
@@ -110,6 +129,7 @@ export const generateOpenApi = (
         in: 'path',
         required: true,
       })),
+      ...(options.setOperationId ? { operationId: path.id } : {}),
       ...(bodySchema
         ? {
             requestBody: {
@@ -136,7 +156,7 @@ export const generateOpenApi = (
   const document: OpenAPIObject = {
     openapi: '3.0.0',
     paths: pathObject,
-    ...options,
+    ...apiDoc,
   };
 
   return document;