feat: enhance parser functionality with operation transformation and definition patching, add new operations module, and improve type handling in method parsing

Author: hairyf

packages/parser/src/parses/common.ts

@@ -6,13 +6,13 @@ import { swagger2ToSwagger3 } from '@genapi/transform'
  * parse OpenAPI info to commits
  * @param source
  */
-export function parseHeaderCommits(source: OpenAPISpecificationV2) {
+export function parseHeaderCommits(source: OpenAPISpecificationV2): string[] {
   const comments = [
     `@title ${source.info.title}`,
     source.info.description != null && source.info.description !== '' && `@description ${source.info.description}`,
     source.swagger && `@swagger ${source.swagger}`,
     `@version ${source.info.version}`,
-  ].filter(Boolean)
+  ].filter((comment): comment is string => typeof comment === 'string')
   return comments
 }
 

packages/parser/src/parses/method.ts

@@ -2,8 +2,9 @@ import type { StatementField, StatementInterface } from '@genapi/shared'
 import type { Parameter } from 'openapi-specification-types'
 import type { PathMethod } from '../traverse'
 import type { InSchemas, LiteralField } from '../utils'
-import { inject } from '@genapi/shared'
+import { inject, provide } from '@genapi/shared'
 import { camelCase } from '@hairy/utils'
+import { transformOperation } from '../transform'
 import { isRequiredParameter, signAnyInter, toUndefField, varName } from '../utils'
 import { parseParameterFiled } from './parameter'
 import { parseSchemaType } from './schema'
@@ -86,6 +87,7 @@ export function parseMethodParameters({ method, parameters, path }: PathMethod,
   // fix: for path required parameters, move to the end
   config.parameters.sort(a => (a.required ? -1 : 1))
 
+  provide(`${method}/${path}`, config)
   return config
 }
 
@@ -100,7 +102,7 @@ export function parseMethodMetadata({ method, path, responses, options: meta }:
     metaAny.consumes?.length ? `@consumes ${metaAny.consumes.join('; ') || '-'}` : undefined,
   ].filter((c): c is string => typeof c === 'string')
 
-  const name = camelCase(`${method}/${path}`)
+  let name = camelCase(`${method}/${path}`)
 
   const url = `${path.replace(/(\{)/g, '${paths.')}`
   function hasContent(r: unknown): r is { content?: Record<string, { schema?: unknown }> } {
@@ -114,7 +116,7 @@ export function parseMethodMetadata({ method, path, responses, options: meta }:
     ?? (content200 && typeof content200 === 'object' && 'schema' in content200 ? (content200 as { schema: unknown }).schema : null)
   const schemaFromRes200 = res200 && typeof res200 === 'object' && 'schema' in res200 && !('content' in res200) ? (res200 as { schema: unknown }).schema : null
   const responseSchema = schemaFromContent ?? schemaFromRes200
-  const responseType = responseSchema && typeof responseSchema === 'object' ? parseSchemaType(responseSchema as Parameters<typeof parseSchemaType>[0]) : 'void'
+  let responseType = responseSchema && typeof responseSchema === 'object' ? parseSchemaType(responseSchema as Parameters<typeof parseSchemaType>[0]) : 'void'
 
   if (configRead.config.responseRequired)
     deepSignRequired(interfaces.find(v => v.name === responseType)?.properties || [])
@@ -128,5 +130,12 @@ export function parseMethodMetadata({ method, path, responses, options: meta }:
     }
   }
 
+  const config = inject(`${method}/${path}`)
+  ;({ name, responseType } = transformOperation({
+    configRead,
+    name,
+    parameters: config?.parameters,
+    responseType,
+  }))
   return { description: comments, name, url, responseType, body: [] as string[] }
 }

packages/parser/src/transform/definitions.ts

@@ -1,4 +1,4 @@
-import type { StatementInterface } from '@genapi/shared'
+import type { ApiPipeline, StatementInterface } from '@genapi/shared'
 import type { Definitions, Schema } from 'openapi-specification-types'
 import { inject } from '@genapi/shared'
 import { parseSchemaType } from '../parses'
@@ -9,17 +9,33 @@ export interface DefinitionTransformOptions {
 }
 
 export function transformDefinitions(definitions: Definitions) {
-  const { interfaces } = inject()
+  const { interfaces, configRead } = inject()
+  const config = (configRead?.config || {}) as ApiPipeline.Config
+  const transformDef = config.transform?.definition
+  const patchDefinitions = config.patch?.definitions || {}
 
   for (const [name, definition] of Object.entries(definitions)) {
     const { properties = {} } = definition
 
+    const interfaceName = varName(name)
+
     interfaces.push({
       export: true,
-      name: varName(name),
+      name: interfaceName,
       properties: Object.keys(properties).map(name => defToFields(name, properties[name])),
     })
 
+    // Build a structural type string for this definition so `transform.definition`
+    // and `patch.definitions` can operate on it.
+    const baseType = buildDefinitionType(interfaceName, properties)
+    applyDefinitionTransformsAndPatches({
+      baseName: interfaceName,
+      baseType,
+      configRead,
+      transformDef,
+      patchDefinitions,
+    })
+
     function defToFields(name: string, propertie: Schema) {
       const required = Array.isArray(definition?.required) ? definition.required.includes(name) : undefined
       const description = propertie.description ? `@description ${propertie.description}` : undefined
@@ -32,3 +48,90 @@ export function transformDefinitions(definitions: Definitions) {
     }
   }
 }
+
+function buildDefinitionType(interfaceName: string, properties: Definitions[string]['properties'] = {}) {
+  const entries = Object.entries(properties)
+  if (entries.length === 0)
+    return 'any'
+
+  const fields = entries.map(([propName, schema]) => {
+    const type = parseSchemaType(schema as Schema)
+    return `${varFiled(propName)}: ${type}`
+  })
+
+  return `{ ${fields.join(', ')} }`
+}
+
+interface DefinitionPatchContext {
+  baseName: string
+  baseType: string
+  configRead: ApiPipeline.ConfigRead
+  transformDef?: (name: string, type: string) => ApiPipeline.Definition
+  patchDefinitions: Record<string, ApiPipeline.Definition>
+}
+
+/**
+ * Applies `config.transform.definition` (global) and `config.patch.definitions` (static)
+ * to a single Swagger/OpenAPI definition.
+ *
+ * Semantics:
+ * - Rename only: `'UserDto': 'User'` → `export type User = UserDto`
+ * - Rename + override type:
+ *   `'SessionDto': { name: 'Session', type: '{ name: string }' }`
+ *   → `export type Session = { name: string }`
+ *
+ * The original interface (e.g. `UserDto`) is preserved so existing references
+ * from schemas remain valid; patches add friendly alias types on top.
+ */
+function applyDefinitionTransformsAndPatches(ctx: DefinitionPatchContext) {
+  const {
+    baseName,
+    baseType,
+    configRead,
+    transformDef,
+    patchDefinitions,
+  } = ctx
+
+  let aliasName = baseName
+  let aliasType = baseType
+
+  function applyPatch(patch?: ApiPipeline.Definition) {
+    if (!patch)
+      return
+
+    if (typeof patch === 'string') {
+      aliasName = patch
+      return
+    }
+
+    if (patch.name)
+      aliasName = patch.name
+    if (patch.type)
+      aliasType = patch.type
+  }
+
+  // Global transform first.
+  if (transformDef) {
+    const patch = transformDef(baseName, baseType)
+    applyPatch(patch)
+  }
+
+  // Then static patch; allow matching by original or transformed name.
+  const staticPatch = patchDefinitions[baseName] ?? patchDefinitions[aliasName]
+  applyPatch(staticPatch)
+
+  const hasNameChange = aliasName !== baseName
+  const hasTypeChange = aliasType !== baseType
+
+  if (!hasNameChange && !hasTypeChange)
+    return
+
+  const aliasValue = hasTypeChange ? aliasType : baseName
+
+  configRead.graphs.typings = configRead.graphs.typings || []
+  configRead.graphs.typings.push({
+    export: true,
+    name: aliasName,
+    value: aliasValue,
+  })
+}

packages/parser/src/transform/index.ts

@@ -1,5 +1,6 @@
 export * from './body'
 export * from './definitions'
 export * from './headers'
+export * from './operations'
 export * from './parameters'
 export * from './urls'

packages/parser/src/transform/operations.ts

@@ -0,0 +1,86 @@
+import type { ApiPipeline, StatementField } from '@genapi/shared'
+
+export interface OperationTransformOptions {
+  /**
+   * Current pipeline config + graphs.
+   */
+  configRead: ApiPipeline.ConfigRead
+  /**
+   * Generated operation name.
+   */
+  name: string
+  /**
+   * Generated parameters (will be mutated in place if overridden).
+   */
+  parameters: StatementField[]
+  /**
+   * Inferred response type for this operation.
+   */
+  responseType: string
+}
+
+/**
+ * Applies `config.transform.operation` (global) and `config.patch.operations` (static)
+ * to a single operation.
+ *
+ * The returned object contains the final `name`, `parameters`, and `responseType`.
+ * Note: `parameters` are always the same array instance passed in; when overridden
+ * by a patch, the array is mutated in place (cleared and re-filled) so callers
+ * using a `const` reference remain valid.
+ *
+ * @group Transform
+ */
+export function transformOperation(options: OperationTransformOptions) {
+  const {
+    configRead,
+    name: originalName,
+    parameters,
+    responseType: originalResponseType,
+  } = options
+
+  const config = configRead.config || {}
+
+  let name = originalName
+  let responseType = originalResponseType
+
+  function applyPatch(patch?: ApiPipeline.Operation) {
+    if (!patch)
+      return
+
+    if (typeof patch === 'string') {
+      name = patch
+      return
+    }
+
+    if (patch.name)
+      name = patch.name
+
+    if (patch.parameters) {
+      // Replace parameters in place so existing references stay valid.
+      parameters.length = 0
+      parameters.push(...patch.parameters)
+    }
+
+    if (patch.responseType != null)
+      responseType = patch.responseType
+  }
+
+  // Global transform first so static patches can target the final name.
+  const transformFn = config.transform?.operation
+  if (transformFn) {
+    const patch = transformFn(name, parameters, responseType)
+    applyPatch(patch)
+  }
+
+  const staticPatchMap = config.patch?.operations
+  if (staticPatchMap) {
+    const staticPatch = staticPatchMap[name]
+    applyPatch(staticPatch)
+  }
+
+  return {
+    name,
+    parameters,
+    responseType,
+  }
+}

packages/presets/src/got/ts/parser/index.ts

@@ -12,7 +12,6 @@ import {
 export const parser = createParser((config, { configRead, functions, interfaces }) => {
   const { parameters, interfaces: attachInters, options } = parseMethodParameters(config)
   let { name, description, url, responseType } = parseMethodMetadata(config)
-
   interfaces.push(...attachInters)
   parameters.push({
     name: 'config',

packages/shared/src/types/config.ts

@@ -1,5 +1,6 @@
 import type { OptionsOfJSONResponseBody } from 'got'
 import type {
+  StatementField,
   StatementFunction,
   StatementImported,
   StatementInterface,
@@ -89,7 +90,73 @@ export namespace ApiPipeline {
     onlyDeclaration?: boolean
   }
 
+  export type Operation = string | {
+    name?: string
+    parameters?: StatementField[]
+    responseType?: string
+  }
+  export type Definition = string | {
+    name?: string
+    type?: string
+  }
+
+  export interface Patch {
+    /**
+     * @example
+     * {
+     *    // change name to updateUserInfo
+     *    postUpdateUserUsingPOST: 'updateUserInfo',
+     *    // change parameters and name
+     *   'getUserUsingGET_1': {
+     *     name: 'getUser',
+     *     parameters: [
+     *       { name: 'id', type: 'string' }
+     *     ]
+     *   }
+     * }
+     */
+    operations?: Record<string, Operation>
+    /**
+     * @example
+     * {
+     *    // rename type
+     *   'UserDto': 'User',
+     *   'OrderDto': 'Order',
+     *   // change type
+     *   'SessionDto': {
+     *     name: 'Session',
+     *     type: '{ name: string, age: number }',
+     *   }
+     * }
+     */
+    definitions?: Record<string, Definition>
+  }
+
+  export interface Transform {
+    /**
+     * @description
+     * Transform the operation
+     */
+    operation: (name: string, parameters: StatementField[], responseType: string) => Operation
+    /**
+     * @description
+     * Transform the definition type
+     */
+    definition: (name: string, type: string) => Definition
+  }
+
   export interface Config extends PreInputs, PreOutput, Meta {
+    /**
+     * @description
+     * Static patches: exact match modification
+     */
+    patch?: Patch
+
+    /**
+     * @description
+     * Transform the operation and definition
+     */
+    transform?: Transform
     /**
      * The compilation pipeline used supports npm package (add the prefix @genapi/ or genapi-) | local path
      * @default 'swag-axios-ts'