feat(openapi): rewrite OpenAPIGenerator (#208)

* wip

* wip

* wip

* wip

* fix types

* utils tests

* custom tests

* wip

* tests

* tests

* disable stripInternal

* @scalar/openapi-types -> openapi-types

* operationId

* fix types

* sync tests

Author: dinwwwh

eslint.config.js

@@ -21,7 +21,7 @@ export default antfu({
     ],
     'no-restricted-imports': ['error', {
       patterns: [{
-        group: ['json-schema-typed', 'json-schema-typed/*'],
+        group: ['json-schema-typed', 'json-schema-typed/*', 'openapi-types', 'openapi-types/*'],
         message: 'Please import from @orpc/openapi instead',
       }],
     }],

packages/contract/src/config.ts

@@ -1,11 +1,11 @@
-import type { HTTPMethod, InputStructure } from './route'
+import type { HTTPMethod, InputStructure, OutputStructure } from './route'
 
 export interface ContractConfig {
   defaultMethod: HTTPMethod
   defaultSuccessStatus: number
   defaultSuccessDescription: string
   defaultInputStructure: InputStructure
-  defaultOutputStructure: InputStructure
+  defaultOutputStructure: OutputStructure
 }
 
 const DEFAULT_CONFIG: ContractConfig = {

packages/openapi/package.json

@@ -73,7 +73,7 @@
     "@orpc/standard-server-fetch": "workspace:*",
     "@orpc/standard-server-node": "workspace:*",
     "json-schema-typed": "^8.0.1",
-    "openapi3-ts": "^4.4.0",
+    "openapi-types": "^12.1.3",
     "rou3": "^0.5.1"
   },
   "devDependencies": {

packages/openapi/src/adapters/standard/index.ts

@@ -1,2 +1,3 @@
 export * from './openapi-codec'
 export * from './openapi-matcher'
+export * from './utils'

packages/openapi/src/adapters/standard/openapi-matcher.ts

@@ -3,7 +3,7 @@ import type { StandardMatcher, StandardMatchResult } from '@orpc/server/standard
 import { type AnyContractProcedure, fallbackContractConfig, type HTTPPath } from '@orpc/contract'
 import { convertPathToHttpPath, createContractedProcedure, eachContractProcedure, getLazyRouterPrefix, getRouterChild, isProcedure, unlazy } from '@orpc/server'
 import { addRoute, createRouter, findRoute } from 'rou3'
-import { standardizeHTTPPath } from '../../utils'
+import { decodeParams, toRou3Pattern } from './utils'
 
 export class OpenAPIMatcher implements StandardMatcher {
   private readonly tree = createRouter<{
@@ -97,14 +97,3 @@ export class OpenAPIMatcher implements StandardMatcher {
     }
   }
 }
-
-/**
- * {@link https://github.com/unjs/rou3}
- */
-function toRou3Pattern(path: HTTPPath): string {
-  return standardizeHTTPPath(path).replace(/\{\+([^}]+)\}/g, '**:$1').replace(/\{([^}]+)\}/g, ':$1')
-}
-
-function decodeParams(params: Record<string, string>): Record<string, string> {
-  return Object.fromEntries(Object.entries(params).map(([key, value]) => [key, decodeURIComponent(value)]))
-}

packages/openapi/src/adapters/standard/utils.test.ts

@@ -0,0 +1,13 @@
+import { decodeParams, toRou3Pattern } from './utils'
+
+it('toRou3Pattern', () => {
+  expect(toRou3Pattern('/api/v1/users/{id}')).toBe('/api/v1/users/:id')
+  expect(toRou3Pattern('/api/v1/users/{+id}')).toBe('/api/v1/users/**:id')
+  expect(toRou3Pattern('/api/v1/users/name')).toBe('/api/v1/users/name')
+  expect(toRou3Pattern('/api/v1/users/name{id}')).toBe('/api/v1/users/name{id}')
+})
+
+it('decodeParams', () => {
+  expect(decodeParams({ id: '1' })).toEqual({ id: '1' })
+  expect(decodeParams({ id: '1%2B1' })).toEqual({ id: '1+1' })
+})

packages/openapi/src/adapters/standard/utils.ts

@@ -0,0 +1,18 @@
+import type { HTTPPath } from '@orpc/contract'
+import { standardizeHTTPPath } from '../../openapi-utils'
+
+/**
+ * {@link https://github.com/unjs/rou3}
+ *
+ * @internal
+ */
+export function toRou3Pattern(path: HTTPPath): string {
+  return standardizeHTTPPath(path).replace(/\/\{\+([^}]+)\}/g, '/**:$1').replace(/\/\{([^}]+)\}/g, '/:$1')
+}
+
+/**
+ * @internal
+ */
+export function decodeParams(params: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(params).map(([key, value]) => [key, decodeURIComponent(value)]))
+}

packages/openapi/src/index.ts

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

packages/openapi/src/openapi-content-builder.ts

@@ -0,0 +1,106 @@
+import type { OpenAPI } from './openapi'
+import { oc } from '@orpc/contract'
+import { os } from '@orpc/server'
+import { applyCustomOpenAPIOperation, customOpenAPIOperation, getCustomOpenAPIOperation } from './openapi-custom'
+
+it('customOpenAPIOperation & getCustomOpenAPIOperation', () => {
+  const customed = customOpenAPIOperation({ value: 123 }, { security: [{ bearerAuth: [] }] })
+
+  expect(customed).toEqual({ value: 123 })
+  expect(getCustomOpenAPIOperation(customed)).toEqual({ security: [{ bearerAuth: [] }] })
+})
+
+describe('applyCustomOpenAPIOperation', () => {
+  it('no custom operation', () => {
+    const procedure = os.handler(() => {})
+
+    const operation: OpenAPI.OperationObject = {
+      parameters: [{
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      }],
+    }
+
+    expect(applyCustomOpenAPIOperation(operation, procedure)).toBe(operation)
+  })
+
+  it('custom at errors', () => {
+    const contract = oc.errors({
+      AUTHENTICATION_FAILED: customOpenAPIOperation({}, {
+        security: [{ bearerAuth: [] }],
+      }),
+      TEST: undefined, // ensure check undefinable error map item
+    })
+
+    const operation: OpenAPI.OperationObject = {
+      parameters: [{
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      }],
+    }
+
+    expect(applyCustomOpenAPIOperation(operation, contract)).toEqual({
+      ...operation,
+      security: [{ bearerAuth: [] }],
+    })
+  })
+
+  it('custom at middlewares', () => {
+    const requiredAuth = os.middleware(({ next }) => next())
+    const procedure = os
+      .use(customOpenAPIOperation(requiredAuth, {
+        security: [{ bearerAuth: [] }],
+      }))
+      .handler(() => {})
+
+    const operation: OpenAPI.OperationObject = {
+      parameters: [{
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      }],
+    }
+
+    expect(applyCustomOpenAPIOperation(operation, procedure)).toEqual({
+      ...operation,
+      security: [{ bearerAuth: [] }],
+    })
+  })
+
+  it('callback override', () => {
+    const requiredAuth = os.middleware(({ next }) => next())
+    const callback = vi.fn()
+    const procedure = os
+      .use(customOpenAPIOperation(requiredAuth, callback))
+      .handler(() => { })
+
+    const operation: OpenAPI.OperationObject = {
+      parameters: [{
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: {
+          type: 'string',
+        },
+      }],
+    }
+
+    callback.mockReturnValue('__mocked__')
+
+    expect(applyCustomOpenAPIOperation(operation, procedure)).toEqual('__mocked__')
+
+    expect(callback).toBeCalledTimes(1)
+    expect(callback).toBeCalledWith(operation, procedure)
+  })
+})