@goast/kotlin 0.7.0-beta.2 → 0.7.1

package/dist/src/generators/services/spring-reactive-web-clients/args.d.ts

@@ -1,114 +1,338 @@
 import type { ApiEndpoint, ApiParameter, ApiSchema, SourceBuilder } from '@goast/core';
 import type { kt } from '../../../ast/index.ts';
 import type { ApiParameterWithMultipartInfo } from '../../../types.ts';
+/**
+ * Empty arguments for `getClientFileContent`. The file content is derived from the generation context alone.
+ */
 export type GetClientFileContent = object;
+/**
+ * Empty arguments for `getRequestsObject`, which builds the Kotlin `object` declaration from the service's endpoints.
+ */
 export type GetRequestsObject = object;
+/**
+ * Arguments for `getEndpointMembers`, which returns the four functions generated for one endpoint. `endpoint` is the
+ * operation, and `parameters` are its query, path, header and request body parameters as collected by
+ * `getAllParameters`.
+ */
 export type GetEndpointMembers = {
     endpoint: ApiEndpoint;
     parameters: ApiParameterWithMultipartInfo[];
 };
+/**
+ * Arguments for `getEndpointFunctionName`. `endpoint` is the operation whose `name` is cased with `functionNameCasing`
+ * to name the `suspend` function.
+ */
 export type GetEndpointFunctionName = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getEndpointDeprecatedAnnotations`. `endpoint` is the operation whose `deprecated` flag decides whether
+ * its functions receive a `@Deprecated("")` annotation.
+ */
 export type GetEndpointDeprecatedAnnotations = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getEndpointFunction`, which generates the `suspend` function that returns the awaited response body.
+ */
 export type GetEndpointFunction = {
+    /**
+     * The operation the `suspend` function is generated for.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters of the function, in the order they appear in its Kotlin signature.
+     */
     parameters: ApiParameterWithMultipartInfo[];
+    /**
+     * The schema of the response body the function returns, or `undefined` when the operation has no response body.
+     */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments for `getEndpointFunctionBody`, which generates the call chain of the `suspend` function.
+ */
 export type GetEndpointFunctionBody = {
+    /**
+     * The operation whose function body is generated.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters the body forwards to the request builder function, in signature order.
+     */
     parameters: ApiParameterWithMultipartInfo[];
+    /**
+     * The response body schema. When present the body awaits it with `awaitBody` and returns it, otherwise it awaits
+     * `awaitBodilessEntity`.
+     */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments for `getEndpointRequestFunctionName`. `endpoint` is the operation whose name, with the `Request` suffix
+ * added, names the request builder function.
+ */
 export type GetEndpointRequestFunctionName = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getEndpointRequestFunction`, which generates the plain function that builds the
+ * `WebClient.RequestHeadersSpec` for one operation.
+ */
 export type GetEndpointRequestFunction = {
+    /**
+     * The operation whose request builder is generated.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters of the request builder, in the order they appear in its Kotlin signature.
+     */
     parameters: ApiParameterWithMultipartInfo[];
+    /**
+     * The response body schema. When present the request builder sets an `Accept: application/json` header.
+     */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments for `getEndpointRequestFunctionBody`, which builds the chain of `WebClient` calls for one operation.
+ */
 export type GetEndpointRequestFunctionBody = {
+    /**
+     * The operation whose request chain is built.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters that feed the URI, body, multipart and header calls of the chain.
+     */
     parameters: ApiParameterWithMultipartInfo[];
+    /**
+     * The response body schema. When present the chain adds `accept(MediaType.APPLICATION_JSON)`.
+     */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments for `getEndpointFunctionWithHandler`, which generates the overload of the `suspend` function that takes a
+ * `responseHandler` and returns its result.
+ */
 export type GetEndpointFunctionWithHandler = {
+    /**
+     * The operation the response handler overload is generated for.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters of the overload, in signature order, before the `responseHandler` parameter.
+     */
     parameters: ApiParameterWithMultipartInfo[];
+    /**
+     * The response body schema. The overload does not use it, but it is part of the shared argument set.
+     */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments for `getEndpointFunctionWithHandlerBody`, which forwards the call of the response handler overload to the
+ * request builder function.
+ */
 export type GetEndpointFunctionWithHandlerBody = {
+    /**
+     * The operation whose overload body is generated.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters forwarded to the request builder function, in signature order.
+     */
     parameters: ApiParameterWithMultipartInfo[];
+    /**
+     * The response body schema. The body does not read it and forwards only the endpoint and the parameters.
+     */
     responseSchema: ApiSchema | undefined;
 };
+/**
+ * Arguments for `getEndpointUriCall`, which builds the `uri(...)` call of a request builder function.
+ */
 export type GetEndpointUriCall = {
+    /**
+     * The operation whose URI call is generated.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters passed to the `<endpoint>Uri` helper. Only used when `preserveUriTemplate` is `false`, in which
+     * case the expanded URI is built by the helper.
+     */
     parameters: ApiParameterWithMultipartInfo[];
 };
+/**
+ * Arguments for `getUriPathVariablesValue`. `endpoint` is the operation whose path parameters become a `mapOf` of URI
+ * variables, or nothing when it has no path parameters.
+ */
 export type GetUriPathVariablesValue = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getUriQueryParameterCalls`. `endpoint` is the operation whose query parameters become `queryParam`
+ * calls, or nothing when it has no query parameters.
+ */
 export type GetUriQueryParameterCalls = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getEndpointUriFunctionName`. `endpoint` is the operation whose name, with the `Uri` suffix
+ * added, names the URI helper function.
+ */
 export type GetEndpointUriFunctionName = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getEndpointUriFunction`, which generates the `<endpoint>Uri` helper that returns the expanded URI.
+ */
 export type GetEndpointUriFunction = {
+    /**
+     * The operation the URI helper is generated for.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameters of the helper, filtered to the path and query parameters.
+     */
     parameters: ApiParameterWithMultipartInfo[];
 };
+/**
+ * Arguments for `getEndpointUriFunctionBody`, which builds the `UriComponentsBuilder` chain of the URI helper.
+ */
 export type GetEndpointUriFunctionBody = {
+    /**
+     * The operation whose path and query parameters the URI helper expands.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * Not read by the body, which takes the path and query parameters from the endpoint itself.
+     */
     parameters: ApiParameterWithMultipartInfo[];
 };
+/**
+ * Arguments for `getParameterToString`, which returns the suffix that converts a parameter value to a string, such as
+ * `.toString()`, `.value` or `.joinToString(",")`.
+ */
 export type GetParameterToString = {
+    /**
+     * The operation the parameter belongs to.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The path, query or header parameter whose value is converted.
+     */
     parameter: ApiParameterWithMultipartInfo;
 };
+/**
+ * Empty arguments for a `getAdditionalClientMembers` hook. The default generator does not define this method, so the
+ * type exists only for subclasses that add it.
+ */
 export type GetAdditionalClientMembers = object;
+/**
+ * Arguments for `getParameterType`, which returns the Kotlin type of a parameter. `endpoint` is the operation
+ * the parameter belongs to, and `parameter` is the one whose type is needed. File parts resolve to `ApiRequestFile`.
+ */
 export type GetParameterType = {
     endpoint: ApiEndpoint;
     parameter: ApiParameterWithMultipartInfo;
 };
+/**
+ * Arguments for a `getRequestBodyType` hook. `endpoint` is the operation whose request body type is wanted. The default
+ * generator does not define or call this method, so the type exists only for subclasses that add it.
+ */
 export type GetRequestBodyType = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getParameterDefaultValue`, which returns the default value expression of an optional parameter.
+ */
 export type GetParameterDefaultValue = {
+    /**
+     * The operation the parameter belongs to.
+     */
     endpoint: ApiEndpoint;
+    /**
+     * The parameter whose default value expression is needed. Required parameters have no default.
+     */
     parameter: ApiParameter;
 };
+/**
+ * Arguments for `getTypeUsage`, which returns the Kotlin type a schema is used as, with the nullability adjusted.
+ *
+ * @template TBuilder The type of the source builder the Kotlin type is written to.
+ */
 export type GetTypeUsage<TBuilder extends SourceBuilder> = {
+    /**
+     * The schema to map to a Kotlin type. An `undefined` schema uses the fallback.
+     */
     schema: ApiSchema | undefined;
+    /**
+     * Overrides the nullability of the mapped type. When omitted the mapped type keeps its own nullability.
+     */
     nullable?: boolean;
+    /**
+     * The type used when the schema maps to no model type.
+     * @default kt.refs.any({ nullable }), i.e. `Any` with the given nullability
+     */
     fallback?: kt.Type<TBuilder>;
 };
+/**
+ * Empty arguments for `getPackageName`, which combines `packageName` and `packageSuffix` into the service's package.
+ */
 export type GetPackageName = object;
+/**
+ * Arguments for `getResponseSchema`. `endpoint` is the operation whose first successful response (a 2xx or unspecified
+ * status) supplies the schema of the response body.
+ */
 export type GetResponseSchema = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getSchemaType`. `schema` is the schema whose Kotlin model reference is looked up in `kotlin.models`,
+ * or `undefined` when there is no schema.
+ */
 export type GetSchemaType = {
     schema: ApiSchema | undefined;
 };
+/**
+ * Arguments for `getAllParameters`. `endpoint` is the operation whose query, path and header parameters are collected,
+ * together with its request body, or with the fields of a multipart request body.
+ */
 export type GetAllParameters = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getRequestBodyParamName`. `endpoint` is the operation whose request body parameter is named after its
+ * model type, or `body` when there is no model type or it is `Any`.
+ */
 export type GetRequestBodyParamName = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getEndpointDocDescription`. `endpoint` is the operation whose description, and its source line when
+ * `includeSourceInDocs` is set, becomes the KDoc of its functions.
+ */
 export type GetEndpointDocDescription = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Empty arguments for `getBasePath`, which derives a base path from the service's first server URL. The default
+ * generator does not call it, so the base path it returns is not written into the generated code.
+ */
 export type GetBasePath = object;
+/**
+ * Arguments for `getEndpointPath`. `endpoint` is the operation whose path, without its leading slashes and after
+ * `pathModifier`, becomes the URI template.
+ */
 export type GetEndpointPath = {
     endpoint: ApiEndpoint;
 };
+/**
+ * Arguments for `getFilePath`. `packageName` is the package whose directory, under `outputDir`, receives the requests
+ * object file.
+ */
 export type GetFilePath = {
     packageName: string;
 };
+/**
+ * Empty arguments for `getRequestsObjectName`, which names the requests object after the service, cased with
+ * `typeNameCasing`.
+ */
 export type GetRequestsObjectName = object;

package/dist/src/generators/services/spring-reactive-web-clients/models.d.ts

@@ -3,15 +3,61 @@ 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 `KotlinSpringReactiveWebClientsGenerator`. Extends the common Kotlin generator options
+ * (`outputDir`, the casing options, `globalImports` and so on) with the options below.
+ *
+ * `springBootVersion` is inherited but has no effect on this generator, because the generated WebFlux client
+ * references no Spring Boot version specific type.
+ */
 export type KotlinSpringReactiveWebClientsGeneratorConfig = KotlinGeneratorConfig & {
+    /**
+     * The base package name of the generated client files. Each service's requests object is placed in the package
+     * `packageName + packageSuffix`, and the default infrastructure package is derived from it.
+     * @default 'com.openapi.generated'
+     */
     packageName: string;
+    /**
+     * The suffix appended to `packageName`, including the leading `.`. Together they form the package of each service's
+     * requests object, which is written to the matching directory under `{outputDir}`. A function receives the service,
+     * so each service can get its own package.
+     * @default '.api.client'
+     */
     packageSuffix: string | ((service?: ApiService) => string);
+    /**
+     * The package of the shared `ApiRequestFile` helper, which clients import for file parameters. A string is used as
+     * written. An object is resolved by its `mode`:
+     * - `append-package-name`: `packageName` followed by `value`.
+     * - `append-full-package-name`: `packageName` and `packageSuffix` followed by `value`.
+     * - `replace`: `value` as written.
+     *
+     * The helper is written to `{outputDir}/{package path}/ApiRequestFile.kt`. With a function-valued `packageSuffix`,
+     * the `append-full-package-name` mode calls it without a service.
+     * @default { mode: 'append-full-package-name', value: '.infrastructure' }, which resolves to
+     * 'com.openapi.generated.api.client.infrastructure'.
+     */
     infrastructurePackageName: string | {
         mode: 'append-package-name' | 'append-full-package-name' | 'replace';
         value: string;
     };
+    /**
+     * Has no effect on this generator. The request URIs are relative to the `WebClient` the caller passes in, which
+     * supplies the base URL, so no base path is written into the generated Kotlin code.
+     * @default undefined
+     */
     basePath?: string | RegExp | ((basePath: string, service: ApiService) => string);
+    /**
+     * Rewrites each endpoint path before it is written into the URI template passed to `WebClient.uri` and into the
+     * `<endpoint>Uri` helper. A function receives the path without its leading slashes and the endpoint, and returns the
+     * new path. A `RegExp` replaces the path with its first match, or keeps the path when nothing matches.
+     * @default undefined
+     */
     pathModifier?: RegExp | ((path: string, endpoint: ApiEndpoint) => string);
+    /**
+     * Has no effect on this generator. Only the OkHttp3 client generator reads it, to configure the serializer it emits.
+     * This generator emits no serializer, so its output does not depend on this value.
+     * @default 'non-absent'
+     */
     serializerJsonInclude: 'always' | 'non-null' | 'non-absent' | 'non-default' | 'non-empty' | 'use-defaults';
     /**
      * Whether the generated request functions pass the URI template (e.g. `pets/{id}`) to `WebClient` instead of an
@@ -28,20 +74,60 @@ export type KotlinSpringReactiveWebClientsGeneratorConfig = KotlinGeneratorConfi
      */
     preserveUriTemplate: boolean;
 };
+/**
+ * The default configuration of the `KotlinSpringReactiveWebClientsGenerator`. It is merged over the common Kotlin
+ * defaults from `defaultKotlinGeneratorConfig`.
+ */
 export declare const defaultKotlinSpringReactiveWebClientsGeneratorConfig: DefaultGenerationProviderConfig<KotlinSpringReactiveWebClientsGeneratorConfig>;
+/**
+ * The input of the `KotlinSpringReactiveWebClientsGenerator`: the output of the `KotlinModelsGenerator`. Each parameter
+ * and response type is resolved through `kotlin.models`, so the models generator must run before this generator.
+ */
 export type KotlinSpringReactiveWebClientsGeneratorInput = KotlinModelsGeneratorOutput;
+/**
+ * The output of the `KotlinSpringReactiveWebClientsGenerator`. It is published under the `kotlin` key, and its
+ * `clients` record lets later generators import the requests object of each service.
+ */
 export type KotlinSpringReactiveWebClientsGeneratorOutput = {
+    /**
+     * The Kotlin results of this generator.
+     */
     kotlin: {
+        /**
+         * The generated requests objects, keyed by service id.
+         */
         clients: {
             [serviceId: string]: KotlinSpringReactiveWebClientGeneratorOutput;
         };
     };
 };
+/**
+ * The output of the `DefaultKotlinSpringReactiveWebClientGenerator` for one service: the name and package of the
+ * generated requests object, stored under `kotlin.clients` for the service's id.
+ */
 export type KotlinSpringReactiveWebClientGeneratorOutput = KotlinImport;
+/**
+ * The context of the `KotlinSpringReactiveWebClientsGenerator`. It extends the services generation context with the
+ * resolved infrastructure package and the reference factories.
+ */
 export type KotlinSpringReactiveWebClientsGeneratorContext = OpenApiServicesGenerationProviderContext<KotlinSpringReactiveWebClientsGeneratorInput, KotlinSpringReactiveWebClientsGeneratorOutput, KotlinSpringReactiveWebClientsGeneratorConfig, KotlinSpringReactiveWebClientGeneratorOutput> & {
+    /**
+     * The resolved package of the shared `ApiRequestFile` helper, as computed from `infrastructurePackageName`.
+     */
     infrastructurePackageName: string;
+    /**
+     * The reference factories this generator uses. `apiRequestFile` references `ApiRequestFile` in the infrastructure
+     * package, so the generated code imports it automatically.
+     */
     refs: ReturnType<typeof getReferenceFactories>;
 };
+/**
+ * The context of the `DefaultKotlinSpringReactiveWebClientGenerator`: the services context plus the service to
+ * generate a requests object for.
+ */
 export type KotlinSpringReactiveWebClientGeneratorContext = KotlinSpringReactiveWebClientsGeneratorContext & {
+    /**
+     * The service whose endpoints are generated into one requests object.
+     */
     service: ApiService;
 };

package/dist/src/generators/services/spring-reactive-web-clients/models.js

@@ -1,4 +1,8 @@
 import { defaultKotlinGeneratorConfig } from '../../../config.js';
+/**
+ * The default configuration of the `KotlinSpringReactiveWebClientsGenerator`. It is merged over the common Kotlin
+ * defaults from `defaultKotlinGeneratorConfig`.
+ */
 export const defaultKotlinSpringReactiveWebClientsGeneratorConfig = {
     ...defaultKotlinGeneratorConfig,
     packageName: 'com.openapi.generated',

package/dist/src/generators/services/spring-reactive-web-clients/refs.d.ts

@@ -1,4 +1,11 @@
 import { kt } from '../../../ast/index.ts';
+/**
+ * Creates the reference factories used by the Spring WebFlux client generators.
+ *
+ * @param infrastructurePackageName The package the shared `ApiRequestFile` helper is written to and imported from.
+ * @returns The reference factories, with `apiRequestFile` referencing `ApiRequestFile` in that package.
+ * @see KotlinSpringReactiveWebClientsGeneratorConfig.infrastructurePackageName
+ */
 export declare function getReferenceFactories(infrastructurePackageName: string): {
     apiRequestFile: kt.ReferenceFactory;
 };

package/dist/src/generators/services/spring-reactive-web-clients/refs.js

@@ -1,5 +1,12 @@
 import { kt } from '../../../ast/index.js';
 // See packages/kotlin/assets/client/spring-reactive-web-clients for reference
+/**
+ * Creates the reference factories used by the Spring WebFlux client generators.
+ *
+ * @param infrastructurePackageName The package the shared `ApiRequestFile` helper is written to and imported from.
+ * @returns The reference factories, with `apiRequestFile` referencing `ApiRequestFile` in that package.
+ * @see KotlinSpringReactiveWebClientsGeneratorConfig.infrastructurePackageName
+ */
 export function getReferenceFactories(infrastructurePackageName) {
     return {
         // ApiRequestFile.kt

package/dist/src/generators/services/spring-reactive-web-clients/spring-reactive-web-client-generator.d.ts

@@ -8,10 +8,46 @@ import type { KotlinSpringReactiveWebClientGeneratorContext, KotlinSpringReactiv
 type Context = KotlinSpringReactiveWebClientGeneratorContext;
 type Output = KotlinSpringReactiveWebClientGeneratorOutput;
 type Builder = KotlinFileBuilder;
+/**
+ * Generates the Spring WebFlux client for one service. Implement it to replace the default client of a service, or
+ * pass a custom implementation to the `KotlinSpringReactiveWebClientsGenerator`.
+ *
+ * @template TOutput The type of the output the generator returns. Defaults to the default service output type.
+ */
 export interface KotlinSpringReactiveWebClientGenerator<TOutput extends Output = Output> {
+    /**
+     * Generates the client for the service in `ctx.service`.
+     * @param ctx The context of the service to generate.
+     * @returns The output for the service, directly or as a promise.
+     */
     generate(ctx: Context): MaybePromise<TOutput>;
 }
+/**
+ * The default generator of a Spring WebFlux client for one service. It writes a single Kotlin file,
+ * `{outputDir}/{package path}/{Name}.kt`, where the package is `packageName + packageSuffix` and `{Name}` is the
+ * service name followed by `_Requests`, cased with `typeNameCasing`.
+ *
+ * The file contains a Kotlin `object` with four functions per endpoint. Their names come from `functionNameCasing`,
+ * shown here with the default camel casing:
+ * - `<endpoint>`: a `suspend` extension function on `WebClient` that returns the response body as its model type, or
+ *   `Unit` without a response body. It awaits the body with `awaitBody`, or with `awaitBodilessEntity` without one.
+ * - `<endpoint>`, overloaded with a `responseHandler` parameter: a `suspend` function `<T : Any>` that passes the
+ *   `ClientResponse` to the handler through `awaitExchange` and returns the handler's result.
+ * - `<endpoint>Request`: a plain function that returns a `WebClient.RequestHeadersSpec<*>` for the request.
+ * - `<endpoint>Uri`: a function that returns the expanded URI `String`. Requests use it only when `preserveUriTemplate`
+ *   is `false`.
+ *
+ * No `Mono` or `Flux` appears in the generated code: the functions suspend instead of returning reactive publishers.
+ * Deprecated operations annotate all four functions with `@Deprecated("")`.
+ *
+ * @see KotlinSpringReactiveWebClientsGenerator
+ */
 export declare class DefaultKotlinSpringReactiveWebClientGenerator extends KotlinFileGenerator<Context, Output> implements KotlinSpringReactiveWebClientGenerator {
+    /**
+     * Writes the requests object file of `ctx.service` and returns its name and package.
+     * @param ctx The context of the service to generate.
+     * @returns The `typeName` and `packageName` of the generated requests object, published under `kotlin.clients`.
+     */
     generate(ctx: Context): MaybePromise<Output>;
     protected getClientFileContent(ctx: Context, args: Args.GetClientFileContent): AppendValueGroup<Builder>;
     protected getRequestsObject(ctx: Context, args: Args.GetRequestsObject): kt.Object<Builder>;

package/dist/src/generators/services/spring-reactive-web-clients/spring-reactive-web-client-generator.js

@@ -3,7 +3,32 @@ import { kt } from '../../../ast/index.js';
 import { KotlinFileBuilder } from '../../../file-builder.js';
 import { getArrayItemStringEnumSchema, getSourceDocLine, getStringEnumSchema, modifyString } from '../../../utils.js';
 import { KotlinFileGenerator } from '../../file-generator.js';
+/**
+ * The default generator of a Spring WebFlux client for one service. It writes a single Kotlin file,
+ * `{outputDir}/{package path}/{Name}.kt`, where the package is `packageName + packageSuffix` and `{Name}` is the
+ * service name followed by `_Requests`, cased with `typeNameCasing`.
+ *
+ * The file contains a Kotlin `object` with four functions per endpoint. Their names come from `functionNameCasing`,
+ * shown here with the default camel casing:
+ * - `<endpoint>`: a `suspend` extension function on `WebClient` that returns the response body as its model type, or
+ *   `Unit` without a response body. It awaits the body with `awaitBody`, or with `awaitBodilessEntity` without one.
+ * - `<endpoint>`, overloaded with a `responseHandler` parameter: a `suspend` function `<T : Any>` that passes the
+ *   `ClientResponse` to the handler through `awaitExchange` and returns the handler's result.
+ * - `<endpoint>Request`: a plain function that returns a `WebClient.RequestHeadersSpec<*>` for the request.
+ * - `<endpoint>Uri`: a function that returns the expanded URI `String`. Requests use it only when `preserveUriTemplate`
+ *   is `false`.
+ *
+ * No `Mono` or `Flux` appears in the generated code: the functions suspend instead of returning reactive publishers.
+ * Deprecated operations annotate all four functions with `@Deprecated("")`.
+ *
+ * @see KotlinSpringReactiveWebClientsGenerator
+ */
 export class DefaultKotlinSpringReactiveWebClientGenerator extends KotlinFileGenerator {
+    /**
+     * Writes the requests object file of `ctx.service` and returns its name and package.
+     * @param ctx The context of the service to generate.
+     * @returns The `typeName` and `packageName` of the generated requests object, published under `kotlin.clients`.
+     */
     generate(ctx) {
         const typeName = this.getRequestsObjectName(ctx, {});
         const packageName = this.getPackageName(ctx, {});

package/dist/src/generators/services/spring-reactive-web-clients/spring-reactive-web-clients-generator.d.ts

@@ -7,8 +7,28 @@ type Output = KotlinSpringReactiveWebClientsGeneratorOutput;
 type Config = KotlinSpringReactiveWebClientsGeneratorConfig;
 type ServiceOutput = KotlinSpringReactiveWebClientGeneratorOutput;
 type Context = KotlinSpringReactiveWebClientsGeneratorContext;
+/**
+ * Generates a Spring WebFlux `WebClient` based Kotlin client for each service.
+ *
+ * Each service produces one file, `{outputDir}/{package path}/{Name}.kt`, where `{Name}` is the service name followed
+ * by `_Requests`, cased with `typeNameCasing`. The file is written by the service generator, which defaults to
+ * `DefaultKotlinSpringReactiveWebClientGenerator`. The shared `ApiRequestFile.kt` helper is also copied to
+ * `{outputDir}/{infrastructure package path}/ApiRequestFile.kt`. Services named `exclude-from-generation` are skipped.
+ *
+ * Publishes the result under `kotlin.clients`, keyed by service id, with the `typeName` and `packageName` of each
+ * requests object, so later generators can import them. Reads the `kotlin.models` output of the models generator.
+ *
+ * `springBootVersion` has no effect on this generator.
+ *
+ * @see KotlinSpringReactiveWebClientsGeneratorOutput
+ */
 export declare class KotlinSpringReactiveWebClientsGenerator extends OpenApiServicesGenerationProviderBase<Input, Output, Config, ServiceOutput, Context> {
     private readonly _serviceGeneratorFactory;
+    /**
+     * Creates the generator.
+     * @param serviceGeneratorFactory Creates the generator that writes the client of each service. Defaults to a
+     * `DefaultKotlinSpringReactiveWebClientGenerator`.
+     */
     constructor(serviceGeneratorFactory?: Factory<KotlinSpringReactiveWebClientGenerator, []>);
     protected generateAdditionalFiles(ctx: Context): Promise<void>;
     protected initResult(): Output;

package/dist/src/generators/services/spring-reactive-web-clients/spring-reactive-web-clients-generator.js

@@ -4,8 +4,28 @@ import { getAssetFileContent } from '../../../assets.js';
 import { defaultKotlinSpringReactiveWebClientsGeneratorConfig, } from './models.js';
 import { getReferenceFactories } from './refs.js';
 import { DefaultKotlinSpringReactiveWebClientGenerator, } from './spring-reactive-web-client-generator.js';
+/**
+ * Generates a Spring WebFlux `WebClient` based Kotlin client for each service.
+ *
+ * Each service produces one file, `{outputDir}/{package path}/{Name}.kt`, where `{Name}` is the service name followed
+ * by `_Requests`, cased with `typeNameCasing`. The file is written by the service generator, which defaults to
+ * `DefaultKotlinSpringReactiveWebClientGenerator`. The shared `ApiRequestFile.kt` helper is also copied to
+ * `{outputDir}/{infrastructure package path}/ApiRequestFile.kt`. Services named `exclude-from-generation` are skipped.
+ *
+ * Publishes the result under `kotlin.clients`, keyed by service id, with the `typeName` and `packageName` of each
+ * requests object, so later generators can import them. Reads the `kotlin.models` output of the models generator.
+ *
+ * `springBootVersion` has no effect on this generator.
+ *
+ * @see KotlinSpringReactiveWebClientsGeneratorOutput
+ */
 export class KotlinSpringReactiveWebClientsGenerator extends OpenApiServicesGenerationProviderBase {
     _serviceGeneratorFactory;
+    /**
+     * Creates the generator.
+     * @param serviceGeneratorFactory Creates the generator that writes the client of each service. Defaults to a
+     * `DefaultKotlinSpringReactiveWebClientGenerator`.
+     */
     constructor(serviceGeneratorFactory) {
         super();
         this._serviceGeneratorFactory =