feat(openapi): override operationId and spec callback for extending operations (#818)

- Allow overriding auto-generated operationId in route configuration
- Accept route.spec as callback function for extending operation objects
- Enable dynamic modification of OpenAPI operation specifications

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added support for explicitly setting an operation ID for endpoints in
OpenAPI integration.
* Enabled dynamic extension of OpenAPI operation objects using a
callback function for advanced customization.

* **Documentation**
* Enhanced OpenAPI documentation with clearer explanations and new
examples for setting operation IDs and extending operation objects.

* **Tests**
* Added new tests to verify dynamic extension and customization of
OpenAPI operation objects.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

apps/content/docs/openapi/openapi-specification.md

@@ -168,12 +168,13 @@ You can enrich your API documentation by specifying operation metadata using the
 ```ts
 const ping = os
   .route({
+    operationId: 'ping', // override auto-generated operationId
     summary: 'the summary',
     description: 'the description',
     deprecated: false,
     tags: ['tag'],
     successDescription: 'the success description',
-    spec: { // override entire auto-generated operation object
+    spec: { // override entire auto-generated operation object, can also be a callback for extending
       operationId: 'customOperationId',
       tags: ['tag'],
       summary: 'the summary',
@@ -204,11 +205,22 @@ const router = os.tag('planets').router({
 
 ### Customizing Operation Objects
 
-You can also extend the operation object using the `.spec` helper for an `error` or `middleware`:
+You can also extend the operation object by defining `route.spec` as a callback, or by using `oo.spec` in errors or middleware:
 
 ```ts
 import { oo } from '@orpc/openapi'
 
+// Using `route.spec` as a callback
+const procedure = os
+  .route({
+    spec: spec => ({
+      ...spec,
+      security: [{ 'api-key': [] }],
+    }),
+  })
+  .handler(() => 'Hello, World!')
+
+// With errors
 const base = os.errors({
   UNAUTHORIZED: oo.spec({
     data: z.any(),
@@ -217,15 +229,14 @@ const base = os.errors({
   })
 })
 
-// OR in middleware
-
+// With middleware
 const requireAuth = oo.spec(
   os.middleware(async ({ next, errors }) => {
     throw new ORPCError('UNAUTHORIZED')
     return next()
   }),
   {
-    security: [{ 'api-key': [] }]
+    security: [{ 'api-key': [] }],
   }
 )
 ```

packages/contract/src/route.ts

@@ -21,6 +21,14 @@ export interface Route {
    */
   path?: HTTPPath
 
+  /**
+   * The operation ID of the endpoint.
+   * This option is typically relevant when integrating with OpenAPI.
+   *
+   * @default Concatenation of router segments
+   */
+  operationId?: string
+
   /**
    * The summary of the procedure.
    * This option is typically relevant when integrating with OpenAPI.
@@ -127,7 +135,7 @@ export interface Route {
    *
    * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification#operation-metadata Operation Metadata Docs}
    */
-  spec?: OpenAPI.OperationObject
+  spec?: OpenAPI.OperationObject | ((current: OpenAPI.OperationObject) => OpenAPI.OperationObject)
 }
 
 export function mergeRoute(a: Route, b: Route): Route {

packages/openapi/src/openapi-generator.test.ts

@@ -57,6 +57,7 @@ const routeTests: TestCase[] = [
   {
     name: 'metadata',
     contract: oc.route({
+      operationId: 'customOperationId',
       tags: ['planets'],
       summary: 'the summary',
       description: 'the description',
@@ -67,6 +68,7 @@ const routeTests: TestCase[] = [
     expected: {
       '/': {
         post: expect.objectContaining({
+          operationId: 'customOperationId',
           tags: ['planets'],
           summary: 'the summary',
           description: 'the description',
@@ -896,6 +898,33 @@ const customOperationTests: TestCase[] = [
       },
     },
   },
+  {
+    name: 'extend operation object',
+    contract: oc
+      .route({
+        spec: spec => ({
+          ...spec,
+          operationId: 'customOperationId',
+          summary: '__OVERRIDE__',
+        }),
+      })
+      .errors({
+        TEST: customOpenAPIOperation({}, { security: [{ bearerAuth: [] }] }),
+      })
+      .input(z.object({ id: z.string() }))
+      .output(z.object({ name: z.string() })),
+    expected: {
+      '/': {
+        post: {
+          operationId: 'customOperationId',
+          summary: '__OVERRIDE__',
+          security: [{ bearerAuth: [] }],
+          requestBody: expect.any(Object),
+          responses: expect.any(Object),
+        },
+      },
+    },
+  },
 ]
 
 it.each([

packages/openapi/src/openapi-generator.ts

@@ -119,7 +119,7 @@ export class OpenAPIGenerator {
     const errors: string[] = []
 
     for (const { contract, path } of contracts) {
-      const operationId = path.join('.')
+      const stringPath = path.join('.')
 
       try {
         const def = contract['~orpc']
@@ -129,12 +129,12 @@ export class OpenAPIGenerator {
 
         let operationObjectRef: OpenAPI.OperationObject
 
-        if (def.route.spec !== undefined) {
+        if (def.route.spec !== undefined && typeof def.route.spec !== 'function') {
           operationObjectRef = def.route.spec
         }
         else {
           operationObjectRef = {
-            operationId,
+            operationId: def.route.operationId ?? stringPath,
             summary: def.route.summary,
             description: def.route.description,
             deprecated: def.route.deprecated,
@@ -146,6 +146,10 @@ export class OpenAPIGenerator {
           await this.#errorResponse(operationObjectRef, def, baseSchemaConvertOptions, undefinedErrorJsonSchema)
         }
 
+        if (typeof def.route.spec === 'function') {
+          operationObjectRef = def.route.spec(operationObjectRef)
+        }
+
         doc.paths ??= {}
         doc.paths[httpPath] ??= {}
         doc.paths[httpPath][method] = applyCustomOpenAPIOperation(operationObjectRef, contract) as any
@@ -156,7 +160,7 @@ export class OpenAPIGenerator {
         }
 
         errors.push(
-          `[OpenAPIGenerator] Error occurred while generating OpenAPI for procedure at path: ${operationId}\n${e.message}`,
+          `[OpenAPIGenerator] Error occurred while generating OpenAPI for procedure at path: ${stringPath}\n${e.message}`,
         )
       }
     }