feat(openapi): .spec for customizing openapi spec (#131)

Author: dinwwwh

packages/openapi/src/index.ts

@@ -1,12 +1,19 @@
 /** unnoq */
 
+import { setOperationExtender } from './openapi-operation-extender'
+
 export * from './json-serializer'
 export * from './openapi'
 export * from './openapi-content-builder'
 export * from './openapi-generator'
+export * from './openapi-operation-extender'
 export * from './openapi-parameters-builder'
 export * from './openapi-path-parser'
 export * from './schema'
 export * from './schema-converter'
 export * from './schema-utils'
 export * from './utils'
+
+export const oo = {
+  spec: setOperationExtender,
+}

packages/openapi/src/openapi-generator.ts

@@ -11,6 +11,7 @@ import { type OpenAPI, OpenApiBuilder } from './openapi'
 import { OpenAPIContentBuilder, type PublicOpenAPIContentBuilder } from './openapi-content-builder'
 import { OpenAPIError } from './openapi-error'
 import { OpenAPIInputStructureParser } from './openapi-input-structure-parser'
+import { extendOperation } from './openapi-operation-extender'
 import { OpenAPIOutputStructureParser } from './openapi-output-structure-parser'
 import { OpenAPIParametersBuilder, type PublicOpenAPIParametersBuilder } from './openapi-parameters-builder'
 import { OpenAPIPathParser } from './openapi-path-parser'
@@ -245,8 +246,10 @@ export class OpenAPIGenerator {
           responses,
         }
 
+        const extendedOperation = extendOperation(operation, contract)
+
         builder.addPath(httpPath, {
-          [method.toLocaleLowerCase()]: operation,
+          [method.toLocaleLowerCase()]: extendedOperation,
         })
       }
       catch (e) {

packages/openapi/src/openapi-operation-extender.ts

@@ -0,0 +1,62 @@
+import type { AnyContractProcedure } from '@orpc/contract'
+import type { OpenAPI } from './openapi'
+import { isProcedure } from '@orpc/server'
+
+const OPERATION_EXTENDER_SYMBOL = Symbol('ORPC_OPERATION_EXTENDER')
+
+export type OverrideOperationValue = OpenAPI.OperationObject
+  | ((current: OpenAPI.OperationObject, procedure: AnyContractProcedure) => OpenAPI.OperationObject)
+
+export function setOperationExtender<T extends object>(o: T, extend: OverrideOperationValue): T {
+  return new Proxy(o, {
+    get(target, prop, receiver) {
+      if (prop === OPERATION_EXTENDER_SYMBOL) {
+        return extend
+      }
+
+      return Reflect.get(target, prop, receiver)
+    },
+  })
+}
+
+export function getOperationExtender(o: object): OverrideOperationValue | undefined {
+  return (o as any)[OPERATION_EXTENDER_SYMBOL] as OverrideOperationValue
+}
+
+export function extendOperation(operation: OpenAPI.OperationObject, procedure: AnyContractProcedure): OpenAPI.OperationObject {
+  const operationExtenders: OverrideOperationValue[] = []
+
+  for (const errorItem of Object.values(procedure['~orpc'].errorMap)) {
+    const maybeExtender = getOperationExtender(errorItem as any)
+
+    if (maybeExtender) {
+      operationExtenders.push(maybeExtender)
+    }
+  }
+
+  if (isProcedure(procedure)) {
+    for (const middleware of procedure['~orpc'].middlewares) {
+      const maybeExtender = getOperationExtender(middleware)
+
+      if (maybeExtender) {
+        operationExtenders.push(maybeExtender)
+      }
+    }
+  }
+
+  let currentOperation = operation
+
+  for (const extender of operationExtenders) {
+    if (typeof extender === 'function') {
+      currentOperation = extender(currentOperation, procedure)
+    }
+    else {
+      currentOperation = {
+        ...currentOperation,
+        ...extender,
+      }
+    }
+  }
+
+  return currentOperation
+}

playgrounds/expressjs/src/orpc.ts

@@ -1,34 +1,45 @@
+import type { ResponseHeadersPluginContext } from '@orpc/server/plugins'
 import type { z } from 'zod'
 import type { UserSchema } from './schemas/user'
+import { oo } from '@orpc/openapi'
 import { ORPCError, os } from '@orpc/server'
 
-export interface ORPCContext {
+export interface ORPCContext extends ResponseHeadersPluginContext {
   user?: z.infer<typeof UserSchema>
   db?: any
 }
 
-export const pub = os
-  .$context<ORPCContext>()
-  .use(async ({ context, path, next }, input) => {
-    const start = Date.now()
+export const base = os.$context<ORPCContext>()
 
-    try {
-      return await next({})
-    }
-    finally {
+export const pub = base.use(async ({ context, path, next }, input) => {
+  const start = Date.now()
+
+  try {
+    return await next({})
+  }
+  finally {
     // eslint-disable-next-line no-console
-      console.log(`[${path.join('/')}] ${Date.now() - start}ms`)
+    console.log(`[${path.join('/')}] ${Date.now() - start}ms`)
+  }
+})
+
+const authMid = oo.spec( // this line is optional, just for customize openapi spec
+  base.middleware(({ context, path, next }, input) => {
+    if (!context.user) {
+      throw new ORPCError('UNAUTHORIZED')
     }
-  })
 
-export const authed = pub.use(({ context, path, next }, input) => {
-  if (!context.user) {
-    throw new ORPCError('UNAUTHORIZED')
-  }
+    return next({
+      context: {
+        user: context.user,
+      },
+    })
+  }),
+  {
+    security: [
+      { bearerAuth: [] },
+    ],
+  },
+)
 
-  return next({
-    context: {
-      user: context.user,
-    },
-  })
-})
+export const authed = base.use(authMid)

playgrounds/openapi/src/orpc.ts

@@ -1,29 +1,30 @@
 import type { ResponseHeadersPluginContext } from '@orpc/server/plugins'
 import type { z } from 'zod'
 import type { UserSchema } from './schemas/user'
+import { oo } from '@orpc/openapi'
 import { ORPCError, os } from '@orpc/server'
 
 export interface ORPCContext extends ResponseHeadersPluginContext {
   user?: z.infer<typeof UserSchema>
   db?: any
 }
 
-export const pub = os
-  .$context<ORPCContext>()
-  .use(async ({ context, path, next }, input) => {
-    const start = Date.now()
+export const base = os.$context<ORPCContext>()
 
-    try {
-      return await next({})
-    }
-    finally {
+export const pub = base.use(async ({ context, path, next }, input) => {
+  const start = Date.now()
+
+  try {
+    return await next({})
+  }
+  finally {
     // eslint-disable-next-line no-console
-      console.log(`[${path.join('/')}] ${Date.now() - start}ms`)
-    }
-  })
+    console.log(`[${path.join('/')}] ${Date.now() - start}ms`)
+  }
+})
 
-export const authed = pub
-  .use(({ context, path, next }, input) => {
+const authMid = oo.spec( // this line is optional, just for customize openapi spec
+  base.middleware(({ context, path, next }, input) => {
     if (!context.user) {
       throw new ORPCError('UNAUTHORIZED')
     }
@@ -33,4 +34,12 @@ export const authed = pub
         user: context.user,
       },
     })
-  })
+  }),
+  {
+    security: [
+      { bearerAuth: [] },
+    ],
+  },
+)
+
+export const authed = base.use(authMid)