@goast/kotlin 0.6.0 → 0.7.0-beta.1

package/src/src/generators/services/spring-controllers/spring-controller-generator.ts

@@ -1,1129 +0,0 @@
-import {
-  type ApiEndpoint,
-  type ApiParameter,
-  type AppendValueGroup,
-  appendValueGroup,
-  type BasicAppendValue,
-  builderTemplate as s,
-  createOverwriteProxy,
-  getSourceDisplayName,
-  type MaybePromise,
-  notNullish,
-  resolveAnyOfAndAllOf,
-  SourceBuilder,
-  toCasing,
-} from '@goast/core';
-
-import { getReasonPhrase } from 'http-status-codes';
-import { kt } from '../../../ast/index.js';
-import type { KotlinImport } from '../../../common-results.js';
-import { KotlinFileBuilder } from '../../../file-builder.js';
-import type { ApiParameterWithMultipartInfo } from '../../../types.js';
-import { getArrayItemStringEnumSchema, getSourceDocLine, getStringEnumSchema, modifyString } from '../../../utils.js';
-import { KotlinFileGenerator } from '../../file-generator.js';
-import type { DefaultKotlinSpringControllerGeneratorArgs as Args } from './index.js';
-import type { KotlinServiceGeneratorContext, KotlinServiceGeneratorOutput } from './models.js';
-
-type Context = KotlinServiceGeneratorContext;
-type Output = KotlinServiceGeneratorOutput;
-type Builder = KotlinFileBuilder;
-
-const strictResponseCustomProperty = 'strict-response';
-
-export interface KotlinSpringControllerGenerator<
-  TOutput extends Output = Output,
-> {
-  generate(ctx: Context): MaybePromise<TOutput>;
-}
-
-export class DefaultKotlinSpringControllerGenerator extends KotlinFileGenerator<Context, Output>
-  implements KotlinSpringControllerGenerator {
-  public generate(
-    ctx: KotlinServiceGeneratorContext,
-  ): MaybePromise<KotlinServiceGeneratorOutput> {
-    const packageName = this.getPackageName(ctx, {});
-    const dirPath = this.getDirectoryPath(ctx, { packageName });
-
-    console.log(`Generating service ${ctx.service.id} to ${dirPath}...`);
-    console.log(`  Endpoints:`);
-    ctx.service.endpoints.forEach((endpoint) => {
-      console.log(
-        `  - ${getSourceDisplayName(ctx.data, endpoint)} [${toCasing(endpoint.name, ctx.config.functionNameCasing)}]`,
-      );
-    });
-    return {
-      apiInterface: this.generateApiInterfaceFile(ctx, {
-        dirPath,
-        packageName,
-      }),
-      apiController: this.generateApiControllerFile(ctx, {
-        dirPath,
-        packageName,
-      }),
-      apiDelegate: this.generateApiDelegateInterfaceFile(ctx, {
-        dirPath,
-        packageName,
-      }),
-    };
-  }
-
-  // #region API Interface
-  protected generateApiInterfaceFile(
-    ctx: Context,
-    args: Args.GenerateApiInterfaceFile,
-  ): KotlinImport {
-    const { dirPath, packageName } = args;
-    const typeName = this.getApiInterfaceName(ctx, {});
-    const fileName = `${typeName}.kt`;
-    const filePath = `${dirPath}/${fileName}`;
-    console.log(`  Generating API interface ${typeName} to ${fileName}...`);
-
-    const builder = new KotlinFileBuilder(packageName, ctx.config);
-    builder.append(
-      this.getApiInterfaceFileContent(ctx, { interfaceName: typeName }),
-    );
-    builder.writeToFile(filePath);
-
-    return { typeName, packageName };
-  }
-
-  protected getApiInterfaceFileContent(
-    ctx: Context,
-    args: Args.GetApiInterfaceFileContent,
-  ): AppendValueGroup<Builder> {
-    const { interfaceName } = args;
-    return appendValueGroup<Builder>(
-      [this.getApiInterface(ctx, { interfaceName })],
-      '\n',
-    );
-  }
-
-  protected getApiInterface(
-    ctx: Context,
-    args: Args.GetApiInterface,
-  ): kt.Interface<Builder> {
-    const { interfaceName } = args;
-
-    return kt.interface(interfaceName, {
-      annotations: this.getApiInterfaceAnnotations(ctx),
-      members: this.getApiInterfaceMembers(ctx),
-      companionObject: kt.object({
-        members: ctx.service.endpoints.map((endpoint) =>
-          kt.property(this.getPathConstantName(ctx, { endpoint }), {
-            const: true,
-            default: kt.string(this.getEndpointPath(ctx, { endpoint })),
-          })
-        ),
-      }),
-    });
-  }
-
-  protected getApiInterfaceAnnotations(ctx: Context): kt.Annotation<Builder>[] {
-    const validated = kt.annotation(kt.refs.spring.validated());
-    const requestMapping = kt.annotation(kt.refs.spring.requestMapping(), [
-      kt.argument(this.getControllerRequestMapping(ctx, { prefix: 'api' })),
-    ]);
-    return [validated, requestMapping];
-  }
-
-  protected getApiInterfaceMembers(ctx: Context): kt.InterfaceMember<Builder>[] {
-    const members: kt.InterfaceMember<Builder>[] = [];
-    const delegateInterfaceName = this.getApiDelegateInterfaceName(ctx, {});
-
-    members.push(
-      kt.function('getDelegate', {
-        returnType: delegateInterfaceName,
-        singleExpression: true,
-        body: kt.object({
-          implements: [delegateInterfaceName],
-        }),
-      }),
-      kt.function('getExceptionHandler', {
-        returnType: ctx.refs.apiExceptionHandler({ nullable: true }),
-        singleExpression: true,
-        body: kt.toNode(null),
-      }),
-    );
-
-    ctx.service.endpoints.forEach((endpoint) => {
-      members.push(this.getApiInterfaceEndpointMethod(ctx, { endpoint }));
-    });
-
-    members.push(
-      ...ctx.service.endpoints
-        .filter((endpoint) => endpoint.custom[strictResponseCustomProperty] ?? ctx.config.strictResponseEntities)
-        .map((endpoint) => this.getApiResponseEntityClass(ctx, { endpoint })),
-    );
-
-    return members;
-  }
-
-  protected getApiInterfaceEndpointMethod(
-    ctx: Context,
-    args: Args.GetApiInterfaceEndpointMethod,
-  ): kt.Function<Builder> {
-    const { endpoint } = args;
-    const parameters = this.getAllParameters(ctx, { endpoint });
-
-    return kt.function(toCasing(endpoint.name, ctx.config.functionNameCasing), {
-      doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint })),
-      suspend: ctx.config.suspendingFunctions,
-      annotations: this.getApiInterfaceEndpointMethodAnnnotations(
-        ctx,
-        endpoint,
-      ),
-      parameters: parameters.map((parameter) => this.getApiInterfaceEndpointMethodParameter(ctx, endpoint, parameter)),
-      returnType: kt.refs.spring.responseEntity(['*']),
-      body: this.getApiInterfaceEndpointMethodBody(ctx, endpoint, parameters),
-    });
-  }
-
-  protected getApiInterfaceEndpointMethodAnnnotations(
-    ctx: Context,
-    endpoint: ApiEndpoint,
-  ): kt.Annotation<Builder>[] {
-    const annotations: kt.Annotation<Builder>[] = [];
-
-    if (ctx.config.addSwaggerAnnotations) {
-      annotations.push(
-        kt.annotation(kt.refs.swagger.operation(), [
-          endpoint.summary ? kt.argument.named('summary', kt.string(endpoint.summary?.trim())) : null,
-          kt.argument.named('operationId', kt.string(endpoint.name)),
-          endpoint.description
-            ? kt.argument.named(
-              'description',
-              kt.string(endpoint.description?.trim()),
-            )
-            : null,
-          endpoint.deprecated !== undefined ? kt.argument.named('deprecated', kt.toNode(endpoint.deprecated)) : null,
-        ]),
-      );
-
-      if (endpoint.responses.length > 0) {
-        annotations.push(
-          kt.annotation(kt.refs.swagger.apiResponses(), [
-            kt.argument.named(
-              'value',
-              kt.collectionLiteral(
-                endpoint.responses.map((response) =>
-                  kt.call(kt.refs.swagger.apiResponse(), [
-                    kt.argument.named(
-                      'responseCode',
-                      // The spec's own response key, not `statusCode`: that field is `undefined` for
-                      // `default` and every range code, and `kt.string(undefined)` renders the bare token
-                      // `null`, which is not assignable to this non-nullable annotation element.
-                      kt.string(response.statusKey),
-                    ),
-                    response.description
-                      ? kt.argument.named(
-                        'description',
-                        kt.string(response.description?.trim()),
-                      )
-                      : null,
-                    kt.argument.named(
-                      'content',
-                      kt.collectionLiteral(
-                        (response.contentOptions.length === 0
-                          ? [{ schema: undefined, type: undefined }]
-                          : response.contentOptions).map(
-                            (content) => {
-                              let schemaType: kt.Type<Builder> = this.getSchemaType(ctx, {
-                                schema: content.schema,
-                              }) ?? kt.refs.any();
-                              let isArray = false;
-
-                              if (kt.refs.list.matches(schemaType)) {
-                                isArray = true;
-                                schemaType = schemaType.generics[0];
-                              }
-
-                              let ktSchema = kt.call(kt.refs.swagger.schema(), [
-                                kt.argument.named(
-                                  'implementation',
-                                  s<Builder>`${schemaType}::class`,
-                                ),
-                              ]);
-                              if (isArray) {
-                                ktSchema = kt.call(kt.refs.swagger.arraySchema(), [
-                                  kt.argument.named('schema', ktSchema),
-                                ]);
-                              }
-
-                              return kt.call(kt.refs.swagger.content(), [
-                                content.type
-                                  ? kt.argument.named(
-                                    'mediaType',
-                                    kt.string(content.type),
-                                  )
-                                  : null,
-                                content.schema
-                                  ? kt.argument.named(
-                                    isArray ? 'array' : 'schema',
-                                    ktSchema,
-                                  )
-                                  : null,
-                              ]);
-                            },
-                          ),
-                      ),
-                    ),
-                  ])
-                ),
-              ),
-            ),
-          ]),
-        );
-      }
-    }
-
-    const requestMapping = kt.annotation(kt.refs.spring.requestMapping(), [
-      kt.argument.named(
-        'method',
-        kt.collectionLiteral([
-          kt.call([
-            kt.refs.spring.requestMethod(),
-            endpoint.method.toUpperCase(),
-          ]),
-        ]),
-      ),
-      kt.argument.named(
-        'value',
-        kt.collectionLiteral([this.getPathConstantName(ctx, { endpoint })]),
-      ),
-    ]);
-    if (endpoint.requestBody && endpoint.requestBody.content.length > 0) {
-      requestMapping.arguments.push(
-        kt.argument.named(
-          'consumes',
-          kt.collectionLiteral(
-            endpoint.requestBody?.content.map((x) => kt.string(x.type)),
-          ),
-        ),
-      );
-    }
-    annotations.push(requestMapping);
-
-    return annotations;
-  }
-
-  protected getApiInterfaceEndpointMethodParameter(
-    ctx: Context,
-    endpoint: ApiEndpoint,
-    parameter: ApiParameterWithMultipartInfo,
-  ): kt.Parameter<Builder> {
-    const enumItemSchema = parameter.multipart ? undefined : getArrayItemStringEnumSchema(parameter.schema);
-    const enumSchema = parameter.multipart ? undefined : getStringEnumSchema(parameter.schema);
-    const enumValueSchema = enumSchema ?? enumItemSchema;
-    const actualType = this.getSchemaType(ctx, { schema: parameter.schema });
-    const isEnumSchema = !!enumValueSchema && !!actualType &&
-      !!this.getSchemaType(ctx, { schema: enumValueSchema });
-    const schemaType = !isEnumSchema
-      ? actualType
-      : enumItemSchema
-      ? kt.refs.list([kt.refs.string()], { nullable: actualType?.nullable })
-      : kt.refs.string({ nullable: actualType?.nullable });
-    const result = kt.parameter(
-      toCasing(parameter.name, ctx.config.parameterNameCasing),
-      this.getParameterType(ctx, {
-        endpoint,
-        parameter,
-        type: isEnumSchema ? schemaType : undefined,
-      }),
-      {
-        default: parameter.multipart && parameter.schema?.default !== undefined
-          ? kt.toNode(parameter.schema?.default)
-          : null,
-      },
-    );
-
-    if (ctx.config.addSwaggerAnnotations) {
-      const annotation = kt.annotation(kt.refs.swagger.parameter(), [
-        parameter.multipart ? kt.argument.named('name', kt.string(parameter.multipart.name)) : null,
-        parameter.description
-          ? kt.argument.named(
-            'description',
-            kt.string(parameter.description?.trim()),
-          )
-          : null,
-        kt.argument.named('required', parameter.required),
-        // Only emitted when set, matching how the model generator marks a deprecated property on `@Schema`.
-        // `@Operation` always states `deprecated`, but doing that for every parameter of every endpoint
-        // would add `deprecated = false` noise far beyond what the annotation is documenting.
-        parameter.deprecated ? kt.argument.named('deprecated', kt.toNode(true)) : null,
-        parameter.target === 'header' ? kt.argument.named('hidden', kt.toNode(true)) : null,
-      ]);
-
-      const schemaArgs: kt.Argument<SourceBuilder>[] = [];
-      if (parameter.schema?.default !== undefined) {
-        schemaArgs.push(
-          kt.argument.named(
-            'defaultValue',
-            kt.string(String(parameter.schema?.default)),
-          ),
-        );
-      }
-      if (isEnumSchema) {
-        schemaArgs.push(
-          kt.argument.named(
-            'allowableValues',
-            kt.collectionLiteral(
-              enumValueSchema?.enum?.map((x) => kt.string(x?.toString())),
-            ),
-          ),
-        );
-      }
-      if (schemaArgs.length) {
-        annotation.arguments.push(
-          kt.argument.named(
-            'schema',
-            kt.call([kt.refs.swagger.schema()], schemaArgs),
-          ),
-        );
-      }
-      result.annotations.push(annotation);
-    }
-
-    const isCorePackage = !schemaType?.packageName ||
-      /^(kotlin|java)(\..*|$)/.test(schemaType.packageName);
-    if (!isCorePackage && ctx.config.addJakartaValidationAnnotations) {
-      result.annotations.push(kt.annotation(kt.refs.jakarta.valid()));
-    }
-
-    if (parameter.target === 'body' && !parameter.multipart) {
-      // A bare @RequestBody is required as far as Spring is concerned, so an optional body has to say so in the
-      // annotation too - the nullable parameter type alone still answers 400 when the body is missing.
-      result.annotations.push(
-        kt.annotation(
-          kt.refs.spring.requestBody(),
-          parameter.required ? [] : [kt.argument.named('required', parameter.required)],
-        ),
-      );
-    }
-
-    if (parameter.target === 'query') {
-      const annotation = kt.annotation(kt.refs.spring.requestParam(), [
-        kt.argument.named('value', kt.string(parameter.name)),
-        kt.argument.named('required', parameter.required),
-      ]);
-      if (parameter.schema?.default !== undefined) {
-        annotation.arguments.push(
-          kt.argument.named(
-            'defaultValue',
-            kt.string(String(parameter.schema?.default)),
-          ),
-        );
-      }
-      result.annotations.push(annotation);
-    }
-
-    if (parameter.target === 'path') {
-      result.annotations.push(
-        kt.annotation(kt.refs.spring.pathVariable(), [
-          kt.string(parameter.name),
-        ]),
-      );
-    }
-
-    if (parameter.target === 'header') {
-      result.annotations.push(
-        kt.annotation(kt.refs.spring.requestHeader(), [
-          kt.string(parameter.name),
-        ]),
-      );
-    }
-
-    if (parameter.multipart) {
-      result.annotations.push(
-        kt.annotation(kt.refs.spring.requestPart(), [
-          kt.argument.named('value', kt.string(parameter.multipart.name)),
-          kt.argument.named('required', parameter.required),
-        ]),
-      );
-    }
-
-    return result;
-  }
-
-  protected getApiInterfaceEndpointMethodBody(
-    ctx: Context,
-    endpoint: ApiEndpoint,
-    parameters: ApiParameterWithMultipartInfo[],
-  ): AppendValueGroup<Builder> {
-    const body = appendValueGroup<Builder>([], '\n');
-
-    parameters.forEach((x) => {
-      const paramName = toCasing(x.name, ctx.config.parameterNameCasing);
-      if (x.multipart) return;
-
-      const enumItemSchema = getArrayItemStringEnumSchema(x.schema);
-      const enumValueSchema = getStringEnumSchema(x.schema) ?? enumItemSchema;
-      if (!enumValueSchema) return;
-
-      const schemaType = this.getSchemaType(ctx, { schema: x.schema });
-      const enumType = this.getSchemaType(ctx, { schema: enumValueSchema });
-      if (schemaType && enumType) {
-        body.values.push(
-          s`val ${paramName} = ${paramName}${schemaType.nullable || (!x.required && !x.schema?.default) ? '?' : ''}.${
-            enumItemSchema ? 'map' : 'let'
-          } { ${enumType}.fromValue(it) ?: return ${kt.refs.spring.responseEntity.infer()}.status(${kt.refs.spring.httpStatus()}.BAD_REQUEST).body(${
-            kt.string(
-              `Invalid value for parameter ${x.name}`,
-            )
-          }) }`,
-        );
-      }
-    });
-
-    body.values.push(
-      s`try {${s.indent`
-          return ${
-        kt.call(
-          [
-            kt.call(kt.reference('getDelegate'), []),
-            toCasing(endpoint.name, ctx.config.functionNameCasing),
-          ],
-          parameters.map((x) => toCasing(x.name, ctx.config.parameterNameCasing)),
-        )
-      }`}
-        } catch (e: ${kt.refs.throwable()}) {${s.indent`
-          return getExceptionHandler()?.handleApiException(e) ?: throw e`}
-        }`,
-    );
-
-    return body;
-  }
-
-  protected getApiResponseEntityClass(
-    ctx: Context,
-    args: Args.GetApiResponseEntityClass,
-  ): kt.Class<Builder> {
-    const { endpoint } = args;
-    const name = this.getApiResponseEntityName(ctx, { endpoint });
-    // Spring 7's `ResponseEntity<T>` carries an `Any` upper bound (JSpecify), so the subclass must bound `T`.
-    // The body parameter is then made nullable (`T?`) to keep null-body ("no response body") responses legal
-    // while staying wire-identical, since Spring's super constructor accepts a `@Nullable T body`.
-    const springBoot4 = ctx.config.springBootVersion === 4;
-    return kt.class(name, {
-      doc: kt.doc(`Response entity for ${endpoint.name}.`),
-      generics: [kt.genericParameter('T', springBoot4 ? { constraint: kt.refs.any() } : undefined)],
-      primaryConstructor: kt.constructor(
-        [
-          kt.parameter.class('body', kt.reference('T', null, springBoot4 ? { nullable: true } : undefined)),
-          kt.parameter.class('rawStatus', kt.refs.int()),
-          kt.parameter.class(
-            'headers',
-            kt.refs.spring.multiValueMap([kt.refs.string(), kt.refs.string()], {
-              nullable: true,
-            }),
-            { default: kt.toNode(null) },
-          ),
-        ],
-        null,
-        {
-          accessModifier: endpoint.responses.length > 0 ? 'private' : null,
-          delegateTarget: 'super',
-          delegateArguments: [
-            kt.argument('body'),
-            kt.argument('headers'),
-            kt.argument('rawStatus'),
-          ],
-        },
-      ),
-      extends: kt.refs.spring.responseEntity([kt.reference('T')]),
-      companionObject: kt.object({
-        members: Array.from(
-          new Set(
-            [
-              ...ctx.config.defaultStatusCodes,
-              501,
-              ...endpoint.responses.map((x) => x.statusCode),
-            ].filter(notNullish),
-          ),
-        ).map((code) => {
-          const fnName = toCasing(
-            getReasonPhrase(code),
-            ctx.config.functionNameCasing,
-          );
-          const response = endpoint.responses.find(
-            (x) => x.statusCode === code,
-          );
-          const responseType = response ? this.getResponseType(ctx, { endpoint, response }) : undefined;
-          const contentType = response?.contentOptions.find(
-            (x) => x.schema,
-          )?.type;
-
-          const hasResponseBody = responseType && !kt.refs.unit.matches(responseType);
-          return kt.function(fnName, {
-            parameters: [
-              hasResponseBody ? kt.parameter.class('body', responseType) : null,
-              kt.parameter.class(
-                'headers',
-                kt.refs.spring.multiValueMap(
-                  [kt.refs.string(), kt.refs.string()],
-                  { nullable: true },
-                ),
-                { default: kt.toNode(null) },
-              ),
-            ],
-            singleExpression: true,
-            body: kt.call(
-              [
-                kt.reference(
-                  this.getApiResponseEntityName(ctx, { endpoint }),
-                  null,
-                  {
-                    generics: [
-                      hasResponseBody
-                        ? responseType
-                        // `Unit?` violates the `T : Any` bound under Spring Boot 4; the `null` body argument
-                        // below stays (now legal because the subclass body parameter is nullable).
-                        : (springBoot4 ? kt.refs.unit() : kt.refs.unit({ nullable: true })),
-                    ],
-                  },
-                ),
-              ],
-              [
-                hasResponseBody ? kt.argument('body') : kt.toNode(null),
-                kt.toNode(code),
-                contentType
-                  ? s`${kt.refs.spring.linkedMultiValueMap([kt.refs.string(), kt.refs.string()])}().also {
-                        if (headers != null) {
-                            it.putAll(headers)
-                        }
-                        it.addIfAbsent("Content-Type", ${kt.string(contentType)})
-                    }`
-                  : kt.argument('headers'),
-              ],
-            ),
-          });
-        }),
-      }),
-    });
-  }
-  // #endregion
-
-  // #region API Controller
-  protected generateApiControllerFile(
-    ctx: Context,
-    args: Args.GenerateApiControllerFile,
-  ): KotlinImport {
-    const { dirPath, packageName } = args;
-    const typeName = this.getApiControllerName(ctx, {});
-    const fileName = `${typeName}.kt`;
-    const filePath = `${dirPath}/${fileName}`;
-    console.log(`  Generating API controller ${typeName} to ${fileName}...`);
-
-    const builder = new KotlinFileBuilder(packageName, ctx.config);
-    builder.append(
-      this.getApiControllerFileContent(ctx, { controllerName: typeName }),
-    );
-    builder.writeToFile(filePath);
-
-    return { typeName, packageName };
-  }
-
-  protected getApiControllerFileContent(
-    ctx: Context,
-    args: Args.GetApiControllerFileContent,
-  ): AppendValueGroup<Builder> {
-    const { controllerName } = args;
-
-    return appendValueGroup(
-      [this.getApiController(ctx, { controllerName })],
-      '\n',
-    );
-  }
-
-  protected getApiController(
-    ctx: Context,
-    args: Args.GetApiController,
-  ): kt.Class<Builder> {
-    const { controllerName } = args;
-
-    return kt.class(controllerName, {
-      annotations: this.getApiControllerAnnotations(ctx),
-      primaryConstructor: kt.constructor([
-        kt.parameter.class(
-          'delegate',
-          kt.reference(this.getApiDelegateInterfaceName(ctx, {}), null, {
-            nullable: true,
-          }),
-          {
-            annotations: [
-              kt.annotation(kt.refs.spring.autowired(), [
-                kt.argument.named('required', 'false'),
-              ]),
-            ],
-          },
-        ),
-        kt.parameter.class(
-          'exceptionHandler',
-          ctx.refs.apiExceptionHandler({ nullable: true }),
-          {
-            annotations: [
-              kt.annotation(kt.refs.spring.autowired(), [
-                kt.argument.named('required', 'false'),
-              ]),
-            ],
-            accessModifier: 'private',
-            property: 'readonly',
-          },
-        ),
-      ]),
-      implements: [this.getApiInterfaceName(ctx, {})],
-      members: this.getApiControllerMembers(ctx),
-    });
-  }
-
-  protected getApiControllerAnnotations(ctx: Context): kt.Annotation<Builder>[] {
-    const annotations: kt.Annotation<Builder>[] = [];
-    if (ctx.config.addJakartaValidationAnnotations) {
-      annotations.push(
-        kt.annotation(kt.refs.jakarta.generated(), [
-          kt.argument.named(
-            'value',
-            kt.collectionLiteral([
-              kt.string('com.goast.kotlin.spring-service-generator'),
-            ]),
-          ),
-        ]),
-      );
-    }
-    annotations.push(kt.annotation(kt.refs.spring.controller()));
-    annotations.push(
-      kt.annotation(kt.refs.spring.requestMapping(), [
-        this.getControllerRequestMapping(ctx, {}),
-      ]),
-    );
-    return annotations;
-  }
-
-  protected getApiControllerMembers(ctx: Context): kt.ClassMember<Builder>[] {
-    const delegateInterfaceName = this.getApiDelegateInterfaceName(ctx, {});
-
-    const delegateProp = kt.property<Builder>('delegate', {
-      accessModifier: 'private',
-      default: s`delegate ?: ${kt.object({ implements: [delegateInterfaceName] })}`,
-    });
-
-    const getDelegateFun = kt.function<Builder>('getDelegate', {
-      override: true,
-      returnType: delegateInterfaceName,
-      singleExpression: true,
-      body: kt.reference('delegate'),
-    });
-
-    const getExceptionHandlerFun = kt.function<Builder>('getExceptionHandler', {
-      override: true,
-      returnType: ctx.refs.apiExceptionHandler({ nullable: true }),
-      singleExpression: true,
-      body: kt.reference('exceptionHandler'),
-    });
-
-    return [delegateProp, getDelegateFun, getExceptionHandlerFun];
-  }
-  // #endregion
-
-  // #region API Delegate Interface
-  protected generateApiDelegateInterfaceFile(
-    ctx: Context,
-    args: Args.GenerateApiDelegateInterfaceFile,
-  ): KotlinImport {
-    const { dirPath, packageName } = args;
-    const typeName = this.getApiDelegateInterfaceName(ctx, {});
-    const fileName = `${typeName}.kt`;
-    const filePath = `${dirPath}/${fileName}`;
-    console.log(`  Generating API delegate ${typeName} to ${fileName}...`);
-
-    const builder = new KotlinFileBuilder(packageName, ctx.config);
-    builder.append(
-      this.getApiDelegateInterfaceFileContent(ctx, {
-        delegateInterfaceName: typeName,
-      }),
-    );
-    builder.writeToFile(filePath);
-
-    return { typeName, packageName };
-  }
-
-  protected getApiDelegateInterfaceFileContent(
-    ctx: Context,
-    args: Args.GetApiDelegateInterfaceFileContent,
-  ): AppendValueGroup<Builder> {
-    const { delegateInterfaceName } = args;
-
-    return appendValueGroup(
-      [this.getApiDelegateInterface(ctx, { delegateInterfaceName })],
-      '\n',
-    );
-  }
-
-  protected getApiDelegateInterface(
-    ctx: Context,
-    args: Args.GetApiDelegateInterface,
-  ): kt.Interface<Builder> {
-    const { delegateInterfaceName } = args;
-
-    return kt.interface(delegateInterfaceName, {
-      annotations: this.getApiDelegateInterfaceAnnotations(ctx),
-      members: this.getApiDelegateInterfaceMembers(ctx),
-    });
-  }
-
-  protected getApiDelegateInterfaceAnnotations(
-    ctx: Context,
-  ): kt.Annotation<Builder>[] {
-    const annotations: kt.Annotation<Builder>[] = [];
-    if (ctx.config.addJakartaValidationAnnotations) {
-      annotations.push(
-        kt.annotation(kt.refs.jakarta.generated(), [
-          kt.argument.named(
-            'value',
-            kt.collectionLiteral([
-              kt.string('com.goast.kotlin.spring-service-generator'),
-            ]),
-          ),
-        ]),
-      );
-    }
-    return annotations;
-  }
-
-  protected getApiDelegateInterfaceMembers(
-    ctx: Context,
-  ): kt.InterfaceMember<Builder>[] {
-    const members: kt.InterfaceMember<Builder>[] = [];
-
-    members.push(
-      kt.function('getRequest', {
-        returnType: kt.refs.java.optional([kt.refs.spring.nativeWebRequest()]),
-        singleExpression: true,
-        body: kt.call([kt.refs.java.optional.infer(), 'empty'], []),
-      }),
-    );
-
-    ctx.service.endpoints.forEach((endpoint) => {
-      members.push(
-        this.getApiDelegateInterfaceEndpointMethod(ctx, { endpoint }),
-      );
-    });
-
-    return members;
-  }
-
-  protected getApiDelegateInterfaceEndpointMethod(
-    ctx: Context,
-    args: Args.GetApiDelegateInterfaceEndpointMethod,
-  ): kt.Function<Builder> {
-    const { endpoint } = args;
-    const parameters = this.getAllParameters(ctx, { endpoint });
-
-    const fn = kt.function<Builder>(
-      toCasing(endpoint.name, ctx.config.functionNameCasing),
-      {
-        doc: kt.doc(this.getEndpointDocDescription(ctx, { endpoint })),
-        suspend: ctx.config.suspendingFunctions,
-        parameters: parameters.map((parameter) => {
-          return kt.parameter(
-            toCasing(parameter.name, ctx.config.parameterNameCasing),
-            this.getParameterType(ctx, { endpoint, parameter }),
-          );
-        }),
-      },
-    );
-
-    if (endpoint.custom[strictResponseCustomProperty] ?? ctx.config.strictResponseEntities) {
-      const responseEntity = kt.reference.genericFactory(
-        this.getApiResponseEntityName(ctx, { endpoint }),
-        `${this.getPackageName(ctx, {})}.${this.getApiInterfaceName(ctx, {})}`,
-      );
-      fn.returnType = responseEntity(['*']);
-      fn.body = appendValueGroup(
-        [
-          s`return ${
-            kt.call(
-              [
-                responseEntity.infer(),
-                toCasing(getReasonPhrase(501), ctx.config.functionNameCasing),
-              ],
-              [],
-            )
-          }`,
-        ],
-        '\n',
-      );
-    } else {
-      fn.returnType = kt.refs.spring.responseEntity([
-        this.getResponseType(ctx, { endpoint }),
-      ]);
-      fn.body = appendValueGroup(
-        [
-          s`return ${kt.refs.spring.responseEntity.infer()}(${kt.refs.spring.httpStatus()}.NOT_IMPLEMENTED)`,
-        ],
-        '\n',
-      );
-    }
-
-    return fn;
-  }
-  // #endregion
-
-  protected getParameterType(
-    ctx: Context,
-    args: Args.GetParameterType,
-  ): kt.Type<Builder> {
-    const { parameter } = args;
-    if (parameter.multipart?.isFile) {
-      return kt.refs.spring.filePart();
-    }
-    const type = this.getTypeUsage(ctx, {
-      schema: parameter.schema,
-      nullable: (!parameter.required && parameter.schema?.default === undefined) ||
-        undefined,
-      type: args.type,
-    });
-    return parameter.target === 'body' ? adjustListType(ctx, type) : type;
-  }
-
-  protected getResponseType(
-    ctx: Context,
-    args: Args.GetResponseType,
-  ): kt.Type<Builder> {
-    const { endpoint, response } = args;
-    const responseSchemas = (response ? [response] : endpoint.responses)
-      .flatMap((x) => x.contentOptions.flatMap((x) => x.schema))
-      .filter(notNullish)
-      .filter(
-        (x, i, a) =>
-          a.findIndex((y) => {
-            const xType = this.getSchemaType(ctx, { schema: x });
-            const yType = this.getSchemaType(ctx, { schema: y });
-            return (
-              xType?.name === yType?.name &&
-              xType?.packageName === yType?.packageName
-            );
-          }) === i,
-      );
-
-    if (responseSchemas.length === 1) {
-      return adjustListType(
-        ctx,
-        this.getTypeUsage(ctx, {
-          schema: responseSchemas[0],
-          fallback: kt.refs.unit(),
-        }),
-      );
-    } else if (responseSchemas.length === 0) {
-      return kt.refs.unit();
-    } else {
-      // Under Spring Boot 4, this type flows into `ResponseEntity<T : Any>` (e.g. the delegate default methods),
-      // so the ambiguous/unknown-body fallback must be non-null `Any` rather than `Any?`.
-      return ctx.config.springBootVersion === 4 ? kt.refs.any() : kt.refs.any({ nullable: true });
-    }
-  }
-
-  protected getTypeUsage(
-    ctx: Context,
-    args: Args.GetTypeUsage<Builder>,
-  ): kt.Type<Builder> {
-    const { schema, nullable, fallback } = args;
-    const type = args.type ?? this.getSchemaType(ctx, { schema });
-    return type
-      ? createOverwriteProxy(type, { nullable: nullable ?? type.nullable })
-      : (fallback ?? kt.refs.any({ nullable }));
-  }
-
-  protected getSchemaType(
-    ctx: Context,
-    args: Args.GetSchemaType,
-  ): kt.Reference<SourceBuilder> | undefined {
-    const { schema } = args;
-    return schema && ctx.input.kotlin.models[schema.id].type;
-  }
-
-  protected getEndpointDocDescription(ctx: Context, args: Args.GetEndpointDocDescription): BasicAppendValue<Builder> {
-    const docSegments = [args.endpoint.description?.trim()];
-
-    if (ctx.config.includeSourceInDocs) {
-      docSegments.push(getSourceDocLine(args.endpoint));
-    }
-
-    return docSegments.filter(notNullish).join('\n\n');
-  }
-
-  protected getControllerRequestMapping(
-    ctx: Context,
-    args: Args.GetControllerRequestMapping,
-  ): kt.String<Builder> {
-    let { prefix } = args;
-    const basePath = this.getBasePath(ctx, {});
-    prefix ??= `openapi.${toCasing(ctx.service.name, ctx.config.propertyNameCasing)}`;
-    return kt.string(`\${${prefix}.base-path:${basePath}}`);
-  }
-
-  protected getBasePath(ctx: Context, _args: Args.GetBasePath): string {
-    return modifyString(
-      (ctx.service.$src ?? ctx.service.endpoints[0]?.$src)?.document
-        .servers?.[0]?.url ?? '/',
-      ctx.config.basePath,
-      ctx.service,
-    );
-  }
-
-  protected getEndpointPath(ctx: Context, args: Args.GetEndpointPath): string {
-    const { endpoint } = args;
-    return modifyString(endpoint.path, ctx.config.pathModifier, endpoint);
-  }
-
-  protected getDirectoryPath(
-    ctx: Context,
-    args: Args.GetDirectoryPath,
-  ): string {
-    const { packageName } = args;
-    return `${ctx.config.outputDir}/${packageName.replace(/\./g, '/')}`;
-  }
-
-  protected getPathConstantName(
-    ctx: Context,
-    args: Args.GetPathConstantName,
-  ): string {
-    const { endpoint } = args;
-    return toCasing(`${endpoint.name}_path`, ctx.config.constantNameCasing);
-  }
-
-  protected getPackageName(ctx: Context, _args: Args.GetPackageName): string {
-    const packageSuffix = typeof ctx.config.packageSuffix === 'string'
-      ? ctx.config.packageSuffix
-      : ctx.config.packageSuffix(ctx.service);
-    return ctx.config.packageName + packageSuffix;
-  }
-
-  protected getApiResponseEntityName(
-    ctx: Context,
-    args: Args.GetApiResponseEntityName,
-  ): string {
-    const { endpoint } = args;
-    return toCasing(
-      `${endpoint.name}_ResponseEntity`,
-      ctx.config.typeNameCasing,
-    );
-  }
-
-  protected getApiInterfaceName(
-    ctx: Context,
-    _args: Args.GetApiInterfaceName,
-  ): string {
-    return toCasing(ctx.service.name + '_Api', ctx.config.typeNameCasing);
-  }
-
-  protected getApiControllerName(
-    ctx: Context,
-    _args: Args.GetApiControllerName,
-  ): string {
-    return toCasing(
-      ctx.service.name + '_ApiController',
-      ctx.config.typeNameCasing,
-    );
-  }
-
-  protected getApiDelegateInterfaceName(
-    ctx: Context,
-    _args: Args.GetApiDelegateInterfaceName,
-  ): string {
-    return toCasing(
-      ctx.service.name + '_ApiDelegate',
-      ctx.config.typeNameCasing,
-    );
-  }
-
-  protected getAllParameters(
-    ctx: Context,
-    args: Args.GetAllParameters,
-  ): ApiParameterWithMultipartInfo[] {
-    const { endpoint } = args;
-    const parameters = endpoint.parameters.filter(
-      (parameter) =>
-        parameter.target === 'query' ||
-        parameter.target === 'path' ||
-        parameter.target === 'header',
-    );
-    if (endpoint.requestBody) {
-      const content = endpoint.requestBody.content[0];
-      let schema = content.schema;
-
-      if (content.type === 'multipart/form-data') {
-        if (schema && schema.kind === 'object') {
-          schema = resolveAnyOfAndAllOf(schema, true) ?? schema;
-          const properties = schema.properties ?? {};
-          for (const [name, property] of properties.entries()) {
-            parameters.push(
-              Object.assign(
-                this.createApiParameter({
-                  id: `multipart-${name}`,
-                  name,
-                  target: 'body',
-                  schema: property.schema,
-                  required: schema.required.has(name),
-                  description: property.schema.description,
-                }),
-                {
-                  multipart: {
-                    name,
-                    isFile: property.schema.kind === 'string' &&
-                      property.schema.format === 'binary',
-                  },
-                },
-              ),
-            );
-          }
-        }
-      } else {
-        const schemaType = this.getSchemaType(ctx, { schema });
-        const name = !schemaType || /^Any\??$/.test(schemaType.name)
-          ? 'body'
-          : SourceBuilder.build((b) => kt.reference.write(b, schemaType));
-        parameters.push(
-          this.createApiParameter({
-            id: 'body',
-            name,
-            target: 'body',
-            schema,
-            required: endpoint.requestBody.required,
-            description: endpoint.requestBody.description,
-          }),
-        );
-      }
-    }
-
-    return parameters;
-  }
-
-  private createApiParameter(
-    data: Partial<ApiParameter> & Pick<ApiParameter, 'id' | 'name' | 'target'>,
-  ): ApiParameter {
-    return {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      $src: undefined!,
-      $ref: undefined,
-      schema: undefined,
-      required: false,
-      description: undefined,
-      allowEmptyValue: undefined,
-      allowReserved: undefined,
-      deprecated: false,
-      explode: undefined,
-      style: undefined,
-      ...data,
-    };
-  }
-}
-
-export function adjustListType<T>(ctx: Context, type: T): T {
-  if (!kt.refs.list.matches(type)) return type;
-  switch (ctx.config.arrayType) {
-    case 'flux':
-      return kt.refs.reactor.flux([type.generics[0]]) as T;
-    default:
-      return type;
-  }
-}