@goast/kotlin 0.7.0 → 0.7.1

package/dist/src/generators/services/spring-controllers/args.d.ts

@@ -1,94 +1,263 @@
 import type { ApiEndpoint, ApiResponse, ApiSchema, SourceBuilder } from '@goast/core';
 import type { kt } from '../../../ast/index.ts';
 import type { ApiParameterWithMultipartInfo } from '../../../types.ts';
+/**
+ * Arguments for writing a file that holds response entity classes. The default generator does not use it, because it
+ * nests the response entity classes in the API interface.
+ */
 export type GenerateApiResponseEntitiesFile = {
+    /**
+     * The directory the file is written to, such as `{outputDir}/com/openapi/generated/api` with the default settings.
+     */
     dirPath: string;
+    /**
+     * The package the file is declared in, with `packageSuffix` already applied.
+     */
     packageName: string;
 };
+/**
+ * Arguments for building the content of a response entities file. The default generator does not use it. The
+ * `packageName` is the package declared at the top of the file, with `packageSuffix` already applied.
+ */
 export type GetApiResponseEntitiesFileContent = {
     packageName: string;
 };
+/**
+ * Arguments for building the response entity classes of a file. It takes no properties, and the default generator
+ * does not call it.
+ */
 export type GetApiResponseEntities = object;
+/**
+ * Arguments for writing the API interface file of a service.
+ */
 export type GenerateApiInterfaceFile = {
+    /**
+     * The directory the interface file is written to, such as `{outputDir}/com/openapi/generated/api`.
+     */
     dirPath: string;
+    /**
+     * The package the interface is declared in, with `packageSuffix` already applied.
+     */
     packageName: string;
 };
+/**
+ * Arguments for building the content of the API interface file. Its `interfaceName` is the name of the interface
+ * declared in the file.
+ */
 export type GetApiInterfaceFileContent = {
     interfaceName: string;
 };
+/**
+ * Arguments for building the API interface declaration, including its functions and path constants. Its
+ * `interfaceName` is the name of the interface, already converted with `typeNameCasing`.
+ */
 export type GetApiInterface = {
     interfaceName: string;
 };
+/**
+ * Arguments for building the interface function of one endpoint. Its `endpoint` is the endpoint whose parameters and
+ * responses determine the signature.
+ */
 export type GetApiInterfaceEndpointMethod = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for building the `{Endpoint}_ResponseEntity` class of one endpoint, which is nested in the API interface.
+ * Its `endpoint` is the endpoint whose response status codes add static factory functions.
+ */
 export type GetApiResponseEntityClass = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for writing the controller file of a service.
+ */
 export type GenerateApiControllerFile = {
+    /**
+     * The directory the controller file is written to, derived from its package below `outputDir`.
+     */
     dirPath: string;
+    /**
+     * The package the controller class is declared in, with `packageSuffix` already applied.
+     */
     packageName: string;
 };
+/**
+ * Arguments for building the content of the controller file. Its `controllerName` is the name of the controller class
+ * declared in the file.
+ */
 export type GetApiControllerFileContent = {
     controllerName: string;
 };
+/**
+ * Arguments for building the controller class, which implements the API interface and forwards to the delegate.
+ * Its `controllerName` is the name of the class, already converted with `typeNameCasing`.
+ */
 export type GetApiController = {
     controllerName: string;
 };
+/**
+ * Arguments for writing the delegate interface file of a service.
+ */
 export type GenerateApiDelegateInterfaceFile = {
+    /**
+     * The directory the delegate file is written to. It is the same directory as the API interface file.
+     */
     dirPath: string;
+    /**
+     * The package the delegate interface is declared in, with `packageSuffix` already applied.
+     */
     packageName: string;
 };
+/**
+ * Arguments for building the content of the delegate interface file. Its `delegateInterfaceName` is the name of the
+ * delegate interface declared in the file.
+ */
 export type GetApiDelegateInterfaceFileContent = {
     delegateInterfaceName: string;
 };
+/**
+ * Arguments for building the delegate interface declaration, which has one function per endpoint. Its
+ * `delegateInterfaceName` is the name of the interface, already converted with `typeNameCasing`.
+ */
 export type GetApiDelegateInterface = {
     delegateInterfaceName: string;
 };
+/**
+ * Arguments for building the delegate function of one endpoint. Its return type follows the endpoint's
+ * `strict-response` setting and `strictResponseEntities`. Its `endpoint` is the endpoint whose responses determine the
+ * default return type.
+ */
 export type GetApiDelegateInterfaceEndpointMethod = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for resolving the Kotlin type of a parameter.
+ */
 export type GetParameterType = {
+    /**
+     * The endpoint the parameter belongs to. The default implementation does not read it.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameter whose type is resolved. Multipart file parts resolve to `FilePart`, and body parameters are
+     * adjusted by `arrayType`.
+     */
     parameter: ApiParameterWithMultipartInfo;
+    /**
+     * A reference that replaces the type derived from the parameter schema, such as `String` for an enum parameter.
+     */
     type?: kt.Reference<SourceBuilder>;
 };
+/**
+ * Arguments for resolving the body type of a response, which becomes the type argument of `ResponseEntity`. Its
+ * `endpoint` is the endpoint whose responses are inspected when `response` is not given. Its `response` is the single
+ * response whose body type is resolved. When omitted, the body types of all responses are combined, and differing body
+ * types resolve to `Any`.
+ */
 export type GetResponseType = {
     endpoint: ApiEndpoint;
     response?: ApiResponse;
 };
+/**
+ * Arguments for resolving the type of a schema in a usage position, such as a parameter or a response body.
+ * @template TBuilder The type of the source builder the resolved type is written to.
+ */
 export type GetTypeUsage<TBuilder extends SourceBuilder> = {
+    /**
+     * The schema the type is derived from. When it is `undefined`, the fallback type is used.
+     */
     schema: ApiSchema | undefined;
+    /**
+     * Overrides the nullability of the resolved type. When omitted, the nullability of the derived type is kept.
+     */
     nullable?: boolean;
+    /**
+     * The type used when no type can be derived from the schema. Defaults to `Any`, nullable when `nullable` is set.
+     */
     fallback?: kt.Type<TBuilder>;
+    /**
+     * A reference that replaces the type derived from the schema.
+     */
     type?: kt.Reference<TBuilder>;
 };
+/**
+ * Arguments for building the KDoc text of an endpoint function. Its `endpoint` is the endpoint whose description is
+ * used, with its source location appended when `includeSourceInDocs` is set.
+ */
 export type GetEndpointDocDescription = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for looking up the type that the models generator assigned to a schema. Its `schema` is looked up in the
+ * `kotlin.models` output by `id`, and `undefined` yields `undefined`.
+ */
 export type GetSchemaType = {
     schema: ApiSchema | undefined;
 };
+/**
+ * Arguments for building the `@RequestMapping` value of the API interface or the controller. Its `prefix` is the
+ * property prefix of the base path placeholder, such as `openapi.pet` in `propertyNameCasing`. The API interface passes
+ * `api`, and the default is `openapi.<service>`.
+ */
 export type GetControllerRequestMapping = {
     prefix?: string;
 };
+/**
+ * Arguments for resolving the base path of a service. It takes no properties, and the service comes from the context.
+ */
 export type GetBasePath = object;
+/**
+ * Arguments for resolving the path of an endpoint as it is written to the path constant. Its `endpoint` is the endpoint
+ * whose path is passed through `pathModifier` first.
+ */
 export type GetEndpointPath = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for resolving the directory that the files of a package are written to. Its `packageName` is the package
+ * whose dots become `/`, below `outputDir`.
+ */
 export type GetDirectoryPath = {
     packageName: string;
 };
+/**
+ * Arguments for naming the constant that holds an endpoint's path in the API interface companion object. Its `endpoint`
+ * is the endpoint whose constant is named: the endpoint name followed by `_path`, in `constantNameCasing`.
+ */
 export type GetPathConstantName = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for resolving the package of a service's files, with `packageSuffix` applied. It takes no properties, and
+ * the service comes from the context.
+ */
 export type GetPackageName = object;
+/**
+ * Arguments for naming the response entity class of an endpoint. Its `endpoint` is the endpoint whose class is named:
+ * the endpoint name plus `_ResponseEntity`.
+ */
 export type GetApiResponseEntityName = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for naming the API interface of a service. It takes no properties, and the service comes from the context.
+ */
 export type GetApiInterfaceName = object;
+/**
+ * Arguments for naming the delegate interface of a service. It takes no properties, and the service comes from the
+ * context.
+ */
 export type GetApiDelegateInterfaceName = object;
+/**
+ * Arguments for naming the controller class of a service. It takes no properties, and the service comes from the
+ * context.
+ */
 export type GetApiControllerName = object;
+/**
+ * Arguments for collecting the parameters of an endpoint, in the order of the generated function signature. Its
+ * `endpoint` is the endpoint whose parameters are collected: path, query and header parameters first, then the request
+ * body, or one parameter per multipart part for `multipart/form-data`.
+ */
 export type GetAllParameters = {
     endpoint: ApiEndpoint;
 };

package/dist/src/generators/services/spring-controllers/models.d.ts

@@ -3,35 +3,155 @@ import type { KotlinImport } from '../../../common-results.ts';
 import { type KotlinGeneratorConfig } from '../../../config.ts';
 import type { KotlinModelsGeneratorOutput } from '../../models/index.ts';
 import type { getReferenceFactories } from './refs.ts';
+/**
+ * The configuration of the spring controllers generator. It extends `KotlinGeneratorConfig`, so the common Kotlin
+ * options apply as well. This generator reads `typeNameCasing` (interface, controller, delegate and response
+ * entity names),
+ * `parameterNameCasing` (parameter names), `functionNameCasing` (functions and status code factories),
+ * `propertyNameCasing` (the base path property prefix), `constantNameCasing` (path constants), `includeSourceInDocs`
+ * (endpoint docs) and `globalImports` (imports).
+ *
+ * `springBootVersion` (`KotlinGeneratorConfig`, `@default 3`) changes this generator's output in these places only:
+ * - `3`: the `T` of a response entity class has no bound, its body parameter is non-null, and the status code factories
+ *   without a body take `Unit?`. Responses whose body types differ resolve to `Any?`.
+ * - `4`: the `T` of a response entity class is bounded by `Any`, its body parameter is `T?`, the status code factories
+ *   without a body take `Unit`, and responses whose body types differ resolve to `Any`. This matches the non-null
+ *   `ResponseEntity<T : Any>` bound of Spring Framework 7.
+ * The Spring types it references come from the same packages for both values, so the imports do not change.
+ * @see KotlinGeneratorConfig
+ */
 export type KotlinServicesGeneratorConfig = KotlinGeneratorConfig & {
+    /**
+     * The base package name. Combined with `packageSuffix`, it gives the package of each service's files and of the
+     * shared `ApiExceptionHandler`.
+     * @default 'com.openapi.generated'
+     */
     packageName: string;
+    /**
+     * The suffix appended to `packageName`, including the leading `.`. A function receives each service and returns the
+     * suffix for that service's files. It receives `null` when `ApiExceptionHandler` is placed, because no service is in
+     * scope there.
+     * @default '.api'
+     */
     packageSuffix: string | ((service: ApiService | null) => string);
+    /**
+     * The base path of each service. It becomes the default of the `${...base-path:...}` placeholder in the
+     * `@RequestMapping` annotations, so Spring can still override it with a property. A string replaces the base path
+     * verbatim. A regular expression is matched against the base path, and its first match replaces it; without a match
+     * the base path is kept. A function receives the base path and the service and returns the new base path. When not
+     * set, the first server URL of the service's document is used, or `/` when there is none.
+     * @default undefined
+     */
     basePath?: string | RegExp | ((basePath: string, service: ApiService) => string);
+    /**
+     * Rewrites the path of each endpoint before it is written to the path constants of the API interface. A regular
+     * expression is matched against the path, and its first match replaces the whole path; without a match the path is
+     * kept. A function receives the path and the endpoint and returns the new path.
+     * @default undefined
+     */
     pathModifier?: RegExp | ((path: string, endpoint: ApiEndpoint) => string);
+    /**
+     * Whether the API interface gets Swagger annotations: `@Operation`, `@ApiResponses` and `@Parameter` on its functions
+     * and parameters, plus the `@Schema` annotations of parameters. Controllers and delegates get none of them.
+     * @default true
+     */
     addSwaggerAnnotations: boolean;
+    /**
+     * Whether Jakarta annotations are added. `@Valid` goes on each parameter whose type is not from
+     * the `kotlin` or `java` packages, and `@Generated` goes on the controller and the delegate interface.
+     * @default true
+     */
     addJakartaValidationAnnotations: boolean;
+    /**
+     * How array types are written for request bodies and response bodies. `'flux'` writes them as `Flux<T>`, and `'list'`
+     * keeps them as `List<T>`. Query, path and header parameters are not affected.
+     * @default 'flux'
+     */
     arrayType: 'list' | 'flux';
+    /**
+     * Whether the endpoint functions of the API interface and the delegate, and `handleApiException` of
+     * `ApiExceptionHandler`, are written with the `suspend` modifier.
+     * @default true
+     */
     suspendingFunctions: boolean;
+    /**
+     * Whether each endpoint gets its own `{Endpoint}_ResponseEntity` class, nested in the API interface. The delegate
+     * function of that endpoint then returns this class, and its default body is the 501 entity of the class. The
+     * endpoint's `strict-response` custom property overrides this setting per endpoint.
+     * @default false
+     */
     strictResponseEntities: boolean;
+    /**
+     * The status codes that get a static factory function in each `{Endpoint}_ResponseEntity` class, named after their
+     * reason phrase, such as `badRequest`. Code 501 is always added, as are the codes of the endpoint's own responses.
+     * Only used when response entity classes are generated, see `strictResponseEntities`.
+     * @default [400, 401, 403, 500, 501]
+     */
     defaultStatusCodes: number[];
 };
+/**
+ * The default configuration of the spring controllers generator. It extends `defaultKotlinGeneratorConfig`.
+ * @see KotlinServicesGeneratorConfig
+ */
 export declare const defaultKotlinServicesGeneratorConfig: DefaultGenerationProviderConfig<KotlinServicesGeneratorConfig>;
+/**
+ * The input of the spring controllers generator, which is the output of the models generator. The type of each request
+ * and response body is looked up in its `kotlin.models` output.
+ * @see KotlinModelsGeneratorOutput
+ */
 export type KotlinServicesGeneratorInput = KotlinModelsGeneratorOutput;
+/**
+ * The output of the spring controllers generator, which later generators read from `kotlin.services`.
+ * @see KotlinServiceGeneratorOutput
+ */
 export type KotlinServicesGeneratorOutput = {
+    /**
+     * The Kotlin output, under which the spring controllers generator publishes `services`.
+     */
     kotlin: {
+        /**
+         * The generated files of each service, keyed by the service id (`ApiService.id`).
+         */
         services: {
             [serviceId: string]: KotlinServiceGeneratorOutput;
         };
     };
 };
+/**
+ * The files written for one service. Each entry gives the type name and package of one generated file.
+ */
 export type KotlinServiceGeneratorOutput = {
+    /**
+     * The API interface, named after the service with an `_Api` suffix.
+     */
     apiInterface: KotlinImport;
+    /**
+     * The controller class, which implements the API interface and forwards each call to the delegate.
+     */
     apiController: KotlinImport;
+    /**
+     * The delegate interface, which has one function per endpoint for the implementation to override.
+     */
     apiDelegate: KotlinImport;
 };
+/**
+ * The context of the spring controllers generator for all services.
+ * @see KotlinServicesGeneratorConfig
+ */
 export type KotlinServicesGeneratorContext = OpenApiServicesGenerationProviderContext<KotlinServicesGeneratorInput, KotlinServicesGeneratorOutput, KotlinServicesGeneratorConfig, KotlinServiceGeneratorOutput> & {
+    /**
+     * The factories for the references to the shared types, created from the configuration.
+     * @see getReferenceFactories
+     */
     refs: ReturnType<typeof getReferenceFactories>;
 };
+/**
+ * The context of the spring controllers generator for one service.
+ * @see KotlinServicesGeneratorContext
+ */
 export type KotlinServiceGeneratorContext = KotlinServicesGeneratorContext & {
+    /**
+     * The service whose files are generated.
+     */
     service: ApiService;
 };

package/dist/src/generators/services/spring-controllers/models.js

@@ -1,4 +1,8 @@
 import { defaultKotlinGeneratorConfig } from '../../../config.js';
+/**
+ * The default configuration of the spring controllers generator. It extends `defaultKotlinGeneratorConfig`.
+ * @see KotlinServicesGeneratorConfig
+ */
 export const defaultKotlinServicesGeneratorConfig = {
     ...defaultKotlinGeneratorConfig,
     packageName: 'com.openapi.generated',

package/dist/src/generators/services/spring-controllers/refs.d.ts

@@ -1,5 +1,14 @@
 import { kt } from '../../../ast/index.ts';
 import type { KotlinServicesGeneratorConfig } from './models.ts';
+/**
+ * Creates the factories for the references to the types that all services share. These types are written once per
+ * run, not once per service, and live in the base package: `packageName` followed by `packageSuffix`.
+ *
+ * A `packageSuffix` function is called with `null` here, because no service is in scope.
+ *
+ * @param options The services generator configuration. Uses `packageName`, `packageSuffix` and `typeNameCasing`.
+ * @returns The reference factories, keyed by reference name. `apiExceptionHandler` references `ApiExceptionHandler`.
+ */
 export declare function getReferenceFactories(options: KotlinServicesGeneratorConfig): {
     apiExceptionHandler: kt.ReferenceFactory;
 };

package/dist/src/generators/services/spring-controllers/refs.js

@@ -1,5 +1,14 @@
 import { toCasing } from '@goast/core';
 import { kt } from '../../../ast/index.js';
+/**
+ * Creates the factories for the references to the types that all services share. These types are written once per
+ * run, not once per service, and live in the base package: `packageName` followed by `packageSuffix`.
+ *
+ * A `packageSuffix` function is called with `null` here, because no service is in scope.
+ *
+ * @param options The services generator configuration. Uses `packageName`, `packageSuffix` and `typeNameCasing`.
+ * @returns The reference factories, keyed by reference name. `apiExceptionHandler` references `ApiExceptionHandler`.
+ */
 export function getReferenceFactories(options) {
     const packageSuffix = typeof options.packageSuffix === 'string' ? options.packageSuffix : options.packageSuffix(null);
     const packageName = options.packageName + packageSuffix;

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

@@ -9,10 +9,31 @@ import type { KotlinServiceGeneratorContext, KotlinServiceGeneratorOutput } from
 type Context = KotlinServiceGeneratorContext;
 type Output = KotlinServiceGeneratorOutput;
 type Builder = KotlinFileBuilder;
+/**
+ * Generates the controller files of one service. Implement it to replace the generation of a service's controllers.
+ * @template TOutput The type of the result, which describes the files that were written.
+ * @see DefaultKotlinSpringControllerGenerator
+ */
 export interface KotlinSpringControllerGenerator<TOutput extends Output = Output> {
+    /**
+     * Writes the files of the service in the context and describes them.
+     * @param ctx The context of the service to generate.
+     * @returns The output that describes the written files, or a promise that resolves to it.
+     */
     generate(ctx: Context): MaybePromise<TOutput>;
 }
+/**
+ * The default generator of the Spring MVC controller files of one service. It writes `{Service}_Api.kt`,
+ * `{Service}_ApiController.kt` and `{Service}_ApiDelegate.kt` into the package directory of the service, below
+ * `{outputDir}`. Each part of the output is built by a protected method, so subclasses can change one part at a time.
+ * @see KotlinSpringControllersGenerator
+ */
 export declare class DefaultKotlinSpringControllerGenerator extends KotlinFileGenerator<Context, Output> implements KotlinSpringControllerGenerator {
+    /**
+     * Writes the API interface, the controller and the delegate interface of the service.
+     * @param ctx The context of the service to generate.
+     * @returns The imports of the three written files, as `apiInterface`, `apiController` and `apiDelegate`.
+     */
     generate(ctx: KotlinServiceGeneratorContext): MaybePromise<KotlinServiceGeneratorOutput>;
     protected generateApiInterfaceFile(ctx: Context, args: Args.GenerateApiInterfaceFile): KotlinImport;
     protected getApiInterfaceFileContent(ctx: Context, args: Args.GetApiInterfaceFileContent): AppendValueGroup<Builder>;
@@ -53,5 +74,13 @@ export declare class DefaultKotlinSpringControllerGenerator extends KotlinFileGe
     protected getAllParameters(ctx: Context, args: Args.GetAllParameters): ApiParameterWithMultipartInfo[];
     private createApiParameter;
 }
+/**
+ * Adjusts an array type for the `arrayType` setting. With `'flux'`, a `List<T>` becomes `Flux<T>`. With `'list'`, or for
+ * any type that is not a `List`, the type is returned unchanged.
+ * @template T The type of the value to adjust, which is a `kt.Type` or a reference to one.
+ * @param ctx The context of the service, which provides `arrayType`.
+ * @param type The type to adjust.
+ * @returns The adjusted type.
+ */
 export declare function adjustListType<T>(ctx: Context, type: T): T;
 export {};

package/dist/src/generators/services/spring-controllers/spring-controller-generator.js

@@ -5,7 +5,18 @@ import { KotlinFileBuilder } from '../../../file-builder.js';
 import { getArrayItemStringEnumSchema, getSourceDocLine, getStringEnumSchema, modifyString } from '../../../utils.js';
 import { KotlinFileGenerator } from '../../file-generator.js';
 const strictResponseCustomProperty = 'strict-response';
+/**
+ * The default generator of the Spring MVC controller files of one service. It writes `{Service}_Api.kt`,
+ * `{Service}_ApiController.kt` and `{Service}_ApiDelegate.kt` into the package directory of the service, below
+ * `{outputDir}`. Each part of the output is built by a protected method, so subclasses can change one part at a time.
+ * @see KotlinSpringControllersGenerator
+ */
 export class DefaultKotlinSpringControllerGenerator extends KotlinFileGenerator {
+    /**
+     * Writes the API interface, the controller and the delegate interface of the service.
+     * @param ctx The context of the service to generate.
+     * @returns The imports of the three written files, as `apiInterface`, `apiController` and `apiDelegate`.
+     */
     generate(ctx) {
         const packageName = this.getPackageName(ctx, {});
         const dirPath = this.getDirectoryPath(ctx, { packageName });
@@ -609,6 +620,14 @@ export class DefaultKotlinSpringControllerGenerator extends KotlinFileGenerator
         };
     }
 }
+/**
+ * Adjusts an array type for the `arrayType` setting. With `'flux'`, a `List<T>` becomes `Flux<T>`. With `'list'`, or for
+ * any type that is not a `List`, the type is returned unchanged.
+ * @template T The type of the value to adjust, which is a `kt.Type` or a reference to one.
+ * @param ctx The context of the service, which provides `arrayType`.
+ * @param type The type to adjust.
+ * @returns The adjusted type.
+ */
 export function adjustListType(ctx, type) {
     if (!kt.refs.list.matches(type))
         return type;

package/dist/src/generators/services/spring-controllers/spring-controllers-generator.d.ts

@@ -8,8 +8,30 @@ type Output = KotlinServicesGeneratorOutput;
 type Config = KotlinServicesGeneratorConfig;
 type ServiceOutput = KotlinServiceGeneratorOutput;
 type Context = KotlinServicesGeneratorContext;
+/**
+ * Generates the Spring MVC controllers of all services. For each service it writes three Kotlin files into
+ * `{outputDir}/{packageDir}`, where `{packageDir}` is `packageName` followed by the service's `packageSuffix`,
+ * with each `.` replaced by `/`. With the default settings this is `{outputDir}/com/openapi/generated/api`.
+ * - `{Service}_Api.kt`: the API interface, with `@RequestMapping` and the path constants in its companion object.
+ * - `{Service}_ApiController.kt`: the `@Controller` class that implements the interface and forwards to the delegate.
+ * - `{Service}_ApiDelegate.kt`: the delegate interface, with one function per endpoint to override.
+ *
+ * The names are the service name plus the `_Api`, `_ApiController` or `_ApiDelegate` suffix, converted with
+ * `typeNameCasing`. Once per run it also writes `{outputDir}/{basePackageDir}/ApiExceptionHandler.kt`, where the base
+ * package is `packageName` followed by the `packageSuffix` for no service. Services named `exclude-from-generation`
+ * are removed from `data.services` before generation.
+ *
+ * Publishes `kotlin.services`, keyed by service id, with `apiInterface`, `apiController` and `apiDelegate`. Each entry
+ * is a `KotlinImport` (`typeName` and `packageName`) that later generators use to reference the file.
+ * @see DefaultKotlinSpringControllerGenerator
+ * @see KotlinServicesGeneratorConfig
+ */
 export declare class KotlinSpringControllersGenerator extends OpenApiServicesGenerationProviderBase<Input, Output, Config, ServiceOutput, Context> {
     private readonly _serviceGeneratorFactory;
+    /**
+     * Initializes a new instance of the KotlinSpringControllersGenerator class.
+     * @param serviceGeneratorFactory Creates the generator of each service. Defaults to the default generator.
+     */
     constructor(serviceGeneratorFactory?: Factory<KotlinSpringControllerGenerator, []>);
     protected initResult(): Output;
     protected generateService(ctx: Context, service: ApiService): MaybePromise<ServiceOutput>;

package/dist/src/generators/services/spring-controllers/spring-controllers-generator.js

@@ -4,8 +4,30 @@ import { KotlinFileBuilder } from '../../../file-builder.js';
 import { defaultKotlinServicesGeneratorConfig, } from './models.js';
 import { getReferenceFactories } from './refs.js';
 import { DefaultKotlinSpringControllerGenerator, } from './spring-controller-generator.js';
+/**
+ * Generates the Spring MVC controllers of all services. For each service it writes three Kotlin files into
+ * `{outputDir}/{packageDir}`, where `{packageDir}` is `packageName` followed by the service's `packageSuffix`,
+ * with each `.` replaced by `/`. With the default settings this is `{outputDir}/com/openapi/generated/api`.
+ * - `{Service}_Api.kt`: the API interface, with `@RequestMapping` and the path constants in its companion object.
+ * - `{Service}_ApiController.kt`: the `@Controller` class that implements the interface and forwards to the delegate.
+ * - `{Service}_ApiDelegate.kt`: the delegate interface, with one function per endpoint to override.
+ *
+ * The names are the service name plus the `_Api`, `_ApiController` or `_ApiDelegate` suffix, converted with
+ * `typeNameCasing`. Once per run it also writes `{outputDir}/{basePackageDir}/ApiExceptionHandler.kt`, where the base
+ * package is `packageName` followed by the `packageSuffix` for no service. Services named `exclude-from-generation`
+ * are removed from `data.services` before generation.
+ *
+ * Publishes `kotlin.services`, keyed by service id, with `apiInterface`, `apiController` and `apiDelegate`. Each entry
+ * is a `KotlinImport` (`typeName` and `packageName`) that later generators use to reference the file.
+ * @see DefaultKotlinSpringControllerGenerator
+ * @see KotlinServicesGeneratorConfig
+ */
 export class KotlinSpringControllersGenerator extends OpenApiServicesGenerationProviderBase {
     _serviceGeneratorFactory;
+    /**
+     * Initializes a new instance of the KotlinSpringControllersGenerator class.
+     * @param serviceGeneratorFactory Creates the generator of each service. Defaults to the default generator.
+     */
     constructor(serviceGeneratorFactory) {
         super();
         this._serviceGeneratorFactory =