diff --git a/mkdocs/docs/en/changelog/changelog.md b/mkdocs/docs/en/changelog/changelog.md index 026276e..05adc1d 100644 --- a/mkdocs/docs/en/changelog/changelog.md +++ b/mkdocs/docs/en/changelog/changelog.md @@ -5,7 +5,21 @@ hide: - navigation --- -## 1.2.18 +## 1.2.19 + +Fixed: + +- Fixed KSP match interceptor tags strictly +- Fixed OpenAPI generator handle multipart byte fields +- Fixed `SchedulingLogger` component provisioning and correct logging levels +- Fixed Cassandra apply `advanced.coalescer.rescheduleInterval` to the driver +- Fixed potential HTTP Client telemetry tags NPE on undefined hosts +- Fixed Jackson downgrade to 2.19.4 due to Kotlin dependencies through BOM +- Fixed Javadoc default retry predicate reference in `RetryConfig` +- Fixed Javadoc for configuration classes from documentation +- Updated Cache annotation retention from class to runtime + +### 1.2.18 Added: diff --git a/mkdocs/docs/en/documentation/general.md b/mkdocs/docs/en/documentation/general.md index ffb2941..fefc6c9 100644 --- a/mkdocs/docs/en/documentation/general.md +++ b/mkdocs/docs/en/documentation/general.md @@ -138,8 +138,8 @@ The `BOM` version is specified once, and the rest of the Kora dependencies are d } dependencies { - annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.18" - implementation platform("ru.tinkoff.kora:kora-parent:1.2.18") + annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.19" + implementation platform("ru.tinkoff.kora:kora-parent:1.2.19") } ``` @@ -165,8 +165,8 @@ The `BOM` version is specified once, and the rest of the Kora dependencies are d } dependencies { - ksp("ru.tinkoff.kora:symbol-processors:1.2.18") - implementation(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + ksp("ru.tinkoff.kora:symbol-processors:1.2.19") + implementation(platform("ru.tinkoff.kora:kora-parent:1.2.19")) } ``` @@ -199,8 +199,8 @@ But the application must also connect the [`BOM`](https://docs.gradle.org/curren ```groovy dependencies { - annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.18" - implementation(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.19" + implementation(platform("ru.tinkoff.kora:kora-parent:1.2.19")) } ``` @@ -210,8 +210,8 @@ But the application must also connect the [`BOM`](https://docs.gradle.org/curren ```kotlin dependencies { - ksp("ru.tinkoff.kora:symbol-processors:1.2.18") - implementation(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + ksp("ru.tinkoff.kora:symbol-processors:1.2.19") + implementation(platform("ru.tinkoff.kora:kora-parent:1.2.19")) } ``` diff --git a/mkdocs/docs/en/documentation/junit5.md b/mkdocs/docs/en/documentation/junit5.md index b3d0574..2de42d3 100644 --- a/mkdocs/docs/en/documentation/junit5.md +++ b/mkdocs/docs/en/documentation/junit5.md @@ -678,7 +678,7 @@ but the tests and will not otherwise be included in the graph: ```groovy dependencies { - testAnnotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.18" + testAnnotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.19" } ``` @@ -688,7 +688,7 @@ but the tests and will not otherwise be included in the graph: ```groovy dependencies { - kspTest("ru.tinkoff.kora:symbol-processors:1.2.18") + kspTest("ru.tinkoff.kora:symbol-processors:1.2.19") } ``` diff --git a/mkdocs/docs/en/documentation/openapi-codegen.md b/mkdocs/docs/en/documentation/openapi-codegen.md index 223f095..6f57681 100644 --- a/mkdocs/docs/en/documentation/openapi-codegen.md +++ b/mkdocs/docs/en/documentation/openapi-codegen.md @@ -1,7 +1,7 @@ --- description: "Explains Kora OpenAPI code generation for HTTP clients and servers, generator options, tags, validation, interceptors, authorization, and JsonNullable support. Use when working with openapi-generator, @HttpClient, @HttpController, @InterceptWith, @Tag, @Validate, JsonNullable, primaryAuth, prefixPath, requestInDelegateParams, HttpClientTokenProvider, PrincipalWithScopes, ApiSecurity." agent: - use_when: "Use this file for Kora docs or implementation questions about Kora OpenAPI code generation for HTTP clients and servers, generator options, tags, validation, interceptors, authorization, and JsonNullable support; key triggers include openapi-generator, @HttpClient, @HttpController, @InterceptWith, @Tag, @Validate, JsonNullable, primaryAuth, prefixPath, requestInDelegateParams, HttpClientTokenProvider, PrincipalWithScopes, ApiSecurity." + use_when: "Use this file for Kora docs or implementation questions about Kora OpenAPI code generation for HTTP clients and servers, generator options, tags, validation, interceptors, authorization, and JsonNullable support; key triggers include openapi-generator, @HttpClient, @HttpController, @InterceptWith, @Tag, @Validate, JsonNullable, primaryAuth, prefixPath, requestInDelegateParams, HttpClientTokenProvider, PrincipalWithScopes, ApiSecurity." --- This module generates Kora code from an `OpenAPI` contract using [OpenAPI Generator](https://openapi-generator.tech/docs/plugins#gradle). @@ -9,7 +9,8 @@ From a single API description, it can create declarative [HTTP server](http-serv as well as request and response models, mappers, authorization handling, and additional annotations. This approach is useful when `OpenAPI` is the source of truth for the transport contract and application code must follow it automatically. -For a step-by-step walkthrough before the reference documentation, see [OpenAPI HTTP Server](../guides/openapi-http-server.md), [Advanced OpenAPI HTTP Server](../guides/openapi-http-server-advanced.md), and [OpenAPI HTTP Client](../guides/openapi-http-client.md). +For a step-by-step walkthrough before the reference documentation, +see [OpenAPI HTTP Server](../guides/openapi-http-server.md), [Advanced OpenAPI HTTP Server](../guides/openapi-http-server-advanced.md), and [OpenAPI HTTP Client](../guides/openapi-http-client.md). ## Dependency { #dependency } @@ -19,7 +20,7 @@ For a step-by-step walkthrough before the reference documentation, see [OpenAPI ```groovy buildscript { dependencies { - classpath("ru.tinkoff.kora:openapi-generator:1.2.18") + classpath("ru.tinkoff.kora:openapi-generator:1.2.19") } } ``` @@ -39,7 +40,7 @@ For a step-by-step walkthrough before the reference documentation, see [OpenAPI ```groovy buildscript { dependencies { - classpath("ru.tinkoff.kora:openapi-generator:1.2.18") + classpath("ru.tinkoff.kora:openapi-generator:1.2.19") } } ``` @@ -69,22 +70,22 @@ In addition to Kora-specific `configOptions`, `GenerateTask` accepts common `Ope They define where to read the contract from, where to put generated files, which packages to use, and how to preprocess the `OpenAPI` description. For Kora projects, these parameters are usually set explicitly because generated code is then added to normal project compilation. -| Parameter | Description | -| -------- | -------- | -| `generatorName` | Generator name (`required`, no default). Always set it to `kora` for Kora. | -| `inputSpec` | Path to the `OpenAPI` file (`required`, no default). Usually this is a file under `src/main/resources/openapi`, for example `$projectDir/src/main/resources/openapi/openapi.yaml`. | -| `outputDir` | Directory for generated files (not specified by default, optional). In Kora projects, this is usually a directory under `build`, for example `$buildDir/generated/openapi`, and it is added to the main source set. | -| `apiPackage` | Package for generated API interfaces, controllers, `delegate` classes, and mappers (default: `org.openapitools.api`). It is recommended to set it explicitly, for example `ru.tinkoff.kora.example.openapi.api`. | -| `modelPackage` | Package for models generated from `OpenAPI` schemas (default: `org.openapitools.model`). It is recommended to set it explicitly, for example `ru.tinkoff.kora.example.openapi.model`. | -| `invokerPackage` | Auxiliary generator package (default: `org.openapitools.api`). It is recommended to set it explicitly next to `apiPackage` and `modelPackage`, for example `ru.tinkoff.kora.example.openapi.invoker`. | -| `configOptions` | Generator-specific parameters (default: `{}`). For Kora, this is where `mode`, `clientConfigPrefix`, `enableServerValidation`, `interceptors`, and the other parameters described below are set. | -| `globalProperties` | Limits which entities are generated (default: `{}`). Useful when you need to generate only `apis`, only `models`, or specific models and operations. Use carefully: normal Kora clients and servers usually need API classes, models, and mappers together. | -| `openapiNormalizer` | Preprocesses the `OpenAPI` contract before generation (default: `{}`). Often used to disable standard transformations with `DISABLE_ALL`, generate only selected operations with `FILTER`, or control rules such as `SIMPLIFY_ONEOF_ANYOF`. | -| `importMappings` | Maps a schema name to an existing class (default: `{}`). Useful when a model is written manually or comes from another module, for example `Money: "com.example.Money"`. | -| `typeMappings` | Maps an `OpenAPI Generator` type to a language type (default: `{}`). Used for targeted type replacement, for example replacing `OffsetDateTime` with a project-specific time type. | -| `schemaMappings` | Maps an `OpenAPI` schema to an external type without generating the model (default: `{}`). Similar to `importMappings`, but configured at schema level and useful for reusing shared DTOs. | -| `skipValidateSpec` | Skips `OpenAPI` contract validation before generation (default: `false`). In normal builds it is better to keep validation enabled; use `true` only temporarily for external contracts that cannot be fixed quickly. | -| `cleanupOutput` | Cleans `outputDir` before generation (default: `false`). Useful when the contract changes often and files from removed operations or models must disappear. Do not point `outputDir` to a directory with handwritten code. | +| Parameter | Description | +|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `generatorName` | Generator name (`required`, no default). Always set it to `kora` for Kora. | +| `inputSpec` | Path to the `OpenAPI` file (`required`, no default). Usually this is a file under `src/main/resources/openapi`, for example `$projectDir/src/main/resources/openapi/openapi.yaml`. | +| `outputDir` | Directory for generated files (not specified by default, optional). In Kora projects, this is usually a directory under `build`, for example `$buildDir/generated/openapi`, and it is added to the main source set. | +| `apiPackage` | Package for generated API interfaces, controllers, `delegate` classes, and mappers (default: `org.openapitools.api`). It is recommended to set it explicitly, for example `ru.tinkoff.kora.example.openapi.api`. | +| `modelPackage` | Package for models generated from `OpenAPI` schemas (default: `org.openapitools.model`). It is recommended to set it explicitly, for example `ru.tinkoff.kora.example.openapi.model`. | +| `invokerPackage` | Auxiliary generator package (default: `org.openapitools.api`). It is recommended to set it explicitly next to `apiPackage` and `modelPackage`, for example `ru.tinkoff.kora.example.openapi.invoker`. | +| `configOptions` | Generator-specific parameters (default: `{}`). For Kora, this is where `mode`, `clientConfigPrefix`, `enableServerValidation`, `interceptors`, and the other parameters described below are set. | +| `globalProperties` | Limits which entities are generated (default: `{}`). Useful when you need to generate only `apis`, only `models`, or specific models and operations. Use carefully: normal Kora clients and servers usually need API classes, models, and mappers together. | +| `openapiNormalizer` | Preprocesses the `OpenAPI` contract before generation (default: `{}`). Often used to disable standard transformations with `DISABLE_ALL`, generate only selected operations with `FILTER`, or control rules such as `SIMPLIFY_ONEOF_ANYOF`. | +| `importMappings` | Maps a schema name to an existing class (default: `{}`). Useful when a model is written manually or comes from another module, for example `Money: "com.example.Money"`. | +| `typeMappings` | Maps an `OpenAPI Generator` type to a language type (default: `{}`). Used for targeted type replacement, for example replacing `OffsetDateTime` with a project-specific time type. | +| `schemaMappings` | Maps an `OpenAPI` schema to an external type without generating the model (default: `{}`). Similar to `importMappings`, but configured at schema level and useful for reusing shared DTOs. | +| `skipValidateSpec` | Skips `OpenAPI` contract validation before generation (default: `false`). In normal builds it is better to keep validation enabled; use `true` only temporarily for external contracts that cannot be fixed quickly. | +| `cleanupOutput` | Cleans `outputDir` before generation (default: `false`). Useful when the contract changes often and files from removed operations or models must disappear. Do not point `outputDir` to a directory with handwritten code. | Example with common options: @@ -169,25 +170,25 @@ Use `globalProperties` only for narrow generation tasks, for example when extrac `openapiNormalizer` changes the input `OpenAPI` contract before generation. It is not a Kora parameter, but a general `OpenAPI Generator` mechanism. For Kora, it is especially useful when one large contract is used by several applications or when the contract contains ambiguous shapes for code generation. -| Rule | Description | -| -------- | -------- | -| `DISABLE_ALL` | Disables standard normalization rules (default: `false`). Starting with `OpenAPI Generator 7`, some rules are enabled by default, so predictable generation often starts with `DISABLE_ALL: "true"` and then enables only the needed rules explicitly. | -| `FILTER` | Keeps only selected operations for generation (not specified by default, optional). Supports one filter at a time: `operationId:name1\|name2`, `method:get\|post`, or `tag:public\|billing`. Operations that do not match are marked as `x-internal: true` and are not generated. | -| `KEEP_ONLY_FIRST_TAG_IN_OPERATION` | Keeps only the first tag on an operation (default: `false`). Useful when operations have several tags and are split into several API classes differently from what you expect. | -| `SET_TAGS_FOR_ALL_OPERATIONS` | Replaces tags on all operations with one provided value (not specified by default, optional). Useful when you want to force one generated API class. | -| `SET_TAGS_TO_OPERATIONID` | Sets an operation tag to `operationId`, or to `default` when `operationId` is empty (default: `false`). Useful for contracts without usable tags when predictable operation grouping is needed. | -| `SET_TAGS_TO_VENDOR_EXTENSION` | Reads operation tags from the specified extension, for example `x-tags` (not specified by default, optional). Useful when an external contract cannot be changed but already has custom operation grouping. | -| `FIX_DUPLICATED_OPERATIONID` | Adds a numeric suffix to duplicated `operationId` values (default: `false`). It is better to fix the contract, but this rule helps generate code for an external description temporarily. | -| `SET_BEARER_AUTH_FOR_NAME` | Converts the specified security scheme to `bearerAuth` (not specified by default, optional). Useful for external contracts where a bearer token is described in a non-standard way but should be handled as a normal bearer scheme in the application. | -| `REF_AS_PARENT_IN_ALLOF` | Marks a `$ref` inside `allOf` as a parent schema with `x-parent: true` (default: `false`). Can help contracts that model inheritance through `allOf`. | -| `SIMPLIFY_ONEOF_ANYOF` | Simplifies some `oneOf`/`anyOf` constructs, for example by moving a `null` variant to `nullable: true` and removing single wrappers (enabled by default in `OpenAPI Generator 7` unless `DISABLE_ALL` is set). For Kora, this can change generated model shapes, so enable it deliberately. | -| `SIMPLIFY_ANYOF_STRING_AND_ENUM_STRING` | Simplifies `anyOf` made from `string` and a string enum to `string` (default: `false`). This can help with contracts where the enum restriction is not important for code. | -| `SIMPLIFY_BOOLEAN_ENUM` | Converts a boolean enum to a plain `boolean` (enabled by default in `OpenAPI Generator 7` unless `DISABLE_ALL` is set). | -| `REFACTOR_ALLOF_WITH_PROPERTIES_ONLY` | Moves properties from a schema that has both `allOf` and `properties` into a separate schema inside `allOf` (enabled by default in `OpenAPI Generator 7` unless `DISABLE_ALL` is set). This can help inheritance, but strict contracts should be checked after generation. | -| `NORMALIZE_31SPEC` | Normalizes some `OpenAPI 3.1` constructs into a form better understood by the generator (default: `false`). Useful for `3.1` contracts when generation fails on newer schema forms. | -| `REMOVE_X_INTERNAL` | Removes `x-internal: true` from operations and models (default: `false`). Use only when the contract already contains `x-internal`, but a specific generation task must force such operations back in. | -| `SET_CONTAINER_TO_NULLABLE` | Marks container types `array`, `set`, or `map` as `nullable` (not specified by default, optional). Use only when an external contract systematically misses `nullable` on such fields. | -| `SET_PRIMITIVE_TYPES_TO_NULLABLE` | Marks primitive types `string`, `integer`, `number`, or `boolean` as `nullable` (not specified by default, optional). This significantly changes model signatures, so apply it only to problematic external contracts. | +| Rule | Description | +|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `DISABLE_ALL` | Disables standard normalization rules (default: `false`). Starting with `OpenAPI Generator 7`, some rules are enabled by default, so predictable generation often starts with `DISABLE_ALL: "true"` and then enables only the needed rules explicitly. | +| `FILTER` | Keeps only selected operations for generation (not specified by default, optional). Supports one filter at a time: `operationId:name1\|name2`, `method:get\|post`, or `tag:public\|billing`. Operations that do not match are marked as `x-internal: true` and are not generated. | +| `KEEP_ONLY_FIRST_TAG_IN_OPERATION` | Keeps only the first tag on an operation (default: `false`). Useful when operations have several tags and are split into several API classes differently from what you expect. | +| `SET_TAGS_FOR_ALL_OPERATIONS` | Replaces tags on all operations with one provided value (not specified by default, optional). Useful when you want to force one generated API class. | +| `SET_TAGS_TO_OPERATIONID` | Sets an operation tag to `operationId`, or to `default` when `operationId` is empty (default: `false`). Useful for contracts without usable tags when predictable operation grouping is needed. | +| `SET_TAGS_TO_VENDOR_EXTENSION` | Reads operation tags from the specified extension, for example `x-tags` (not specified by default, optional). Useful when an external contract cannot be changed but already has custom operation grouping. | +| `FIX_DUPLICATED_OPERATIONID` | Adds a numeric suffix to duplicated `operationId` values (default: `false`). It is better to fix the contract, but this rule helps generate code for an external description temporarily. | +| `SET_BEARER_AUTH_FOR_NAME` | Converts the specified security scheme to `bearerAuth` (not specified by default, optional). Useful for external contracts where a bearer token is described in a non-standard way but should be handled as a normal bearer scheme in the application. | +| `REF_AS_PARENT_IN_ALLOF` | Marks a `$ref` inside `allOf` as a parent schema with `x-parent: true` (default: `false`). Can help contracts that model inheritance through `allOf`. | +| `SIMPLIFY_ONEOF_ANYOF` | Simplifies some `oneOf`/`anyOf` constructs, for example by moving a `null` variant to `nullable: true` and removing single wrappers (enabled by default in `OpenAPI Generator 7` unless `DISABLE_ALL` is set). For Kora, this can change generated model shapes, so enable it deliberately. | +| `SIMPLIFY_ANYOF_STRING_AND_ENUM_STRING` | Simplifies `anyOf` made from `string` and a string enum to `string` (default: `false`). This can help with contracts where the enum restriction is not important for code. | +| `SIMPLIFY_BOOLEAN_ENUM` | Converts a boolean enum to a plain `boolean` (enabled by default in `OpenAPI Generator 7` unless `DISABLE_ALL` is set). | +| `REFACTOR_ALLOF_WITH_PROPERTIES_ONLY` | Moves properties from a schema that has both `allOf` and `properties` into a separate schema inside `allOf` (enabled by default in `OpenAPI Generator 7` unless `DISABLE_ALL` is set). This can help inheritance, but strict contracts should be checked after generation. | +| `NORMALIZE_31SPEC` | Normalizes some `OpenAPI 3.1` constructs into a form better understood by the generator (default: `false`). Useful for `3.1` contracts when generation fails on newer schema forms. | +| `REMOVE_X_INTERNAL` | Removes `x-internal: true` from operations and models (default: `false`). Use only when the contract already contains `x-internal`, but a specific generation task must force such operations back in. | +| `SET_CONTAINER_TO_NULLABLE` | Marks container types `array`, `set`, or `map` as `nullable` (not specified by default, optional). Use only when an external contract systematically misses `nullable` on such fields. | +| `SET_PRIMITIVE_TYPES_TO_NULLABLE` | Marks primitive types `string`, `integer`, `number`, or `boolean` as `nullable` (not specified by default, optional). This significantly changes model signatures, so apply it only to problematic external contracts. | Example of generating only the public part of a contract: @@ -247,15 +248,15 @@ Example of normalizing tags for a contract without convenient grouping: Kora also supports several `configOptions` that control `JSON` mappers and common model generation. They do not depend on whether a client or a server is generated. -| Parameter | Description | -| -------- | -------- | -| `jsonAnnotation` | Annotation tag used to inject `JSON` mappers into generated request and response mappers (default: `ru.tinkoff.kora.json.common.annotation.Json`). | -| `objectType` | Type for `type: object` schemas without a more precise description. `Java` uses `java.lang.Object` by default, and `Kotlin` uses `kotlin.Any`. For example, set it to `com.fasterxml.jackson.databind.JsonNode` if the application wants to handle arbitrary `JSON` as a tree. | -| `disableHtmlEscaping` | Disables HTML character escaping in `JSON` strings (default: `false`). Usually the default value is kept. | -| `ignoreAnyOfInEnum` | Ignores `anyOf` when generating enums (default: `false`). Can help with contracts where an enum is described through mixed `anyOf` constructs. | -| `discriminatorCaseSensitive` | Controls case sensitivity of the discriminator value lookup for polymorphic (`oneOf`) models with a discriminator (default: `true`). Set to `false` when incoming discriminator values may differ in case from the schema definition. | -| `additionalModelTypeAnnotations` | Additional annotations on model types (not specified by default, optional). Several annotations are separated by `;`, for example `@Deprecated;@MyAnnotation`. | -| `additionalEnumTypeAnnotations` | Additional annotations on enum types (not specified by default, optional). Several annotations are separated by `;`. | +| Parameter | Description | +|----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `jsonAnnotation` | Annotation tag used to inject `JSON` mappers into generated request and response mappers (default: `ru.tinkoff.kora.json.common.annotation.Json`). | +| `objectType` | Type for `type: object` schemas without a more precise description. `Java` uses `java.lang.Object` by default, and `Kotlin` uses `kotlin.Any`. For example, set it to `com.fasterxml.jackson.databind.JsonNode` if the application wants to handle arbitrary `JSON` as a tree. | +| `disableHtmlEscaping` | Disables HTML character escaping in `JSON` strings (default: `false`). Usually the default value is kept. | +| `ignoreAnyOfInEnum` | Ignores `anyOf` when generating enums (default: `false`). Can help with contracts where an enum is described through mixed `anyOf` constructs. | +| `discriminatorCaseSensitive` | Controls case sensitivity of the discriminator value lookup for polymorphic (`oneOf`) models with a discriminator (default: `true`). Set to `false` when incoming discriminator values may differ in case from the schema definition. | +| `additionalModelTypeAnnotations` | Additional annotations on model types (not specified by default, optional). Several annotations are separated by `;`, for example `@Deprecated;@MyAnnotation`. | +| `additionalEnumTypeAnnotations` | Additional annotations on enum types (not specified by default, optional). Several annotations are separated by `;`. | Example: @@ -507,13 +508,13 @@ The full set of client options (`url`, `requestTimeout`, per-operation blocks, ` The client method signatures depend on the selected `mode`: -| Mode | Return type example | -| -------- | -------- | -| `java-client` | `PetApiResponses.GetPetByIdApiResponse` (blocking value) | -| `java-async-client` | `CompletionStage` | -| `java-reactive-client` | `Mono` (requires `reactor-core`) | -| `kotlin-client` | `PetApiResponses.GetPetByIdApiResponse` (blocking value) | -| `kotlin-suspend-client` | `suspend fun ...: PetApiResponses.GetPetByIdApiResponse` | +| Mode | Return type example | +|-------------------------|-------------------------------------------------------------------------| +| `java-client` | `PetApiResponses.GetPetByIdApiResponse` (blocking value) | +| `java-async-client` | `CompletionStage` | +| `java-reactive-client` | `Mono` (requires `reactor-core`) | +| `kotlin-client` | `PetApiResponses.GetPetByIdApiResponse` (blocking value) | +| `kotlin-suspend-client` | `suspend fun ...: PetApiResponses.GetPetByIdApiResponse` | Every method returns a sealed `*ApiResponses` envelope whose subtypes encode the HTTP status, the same way [server delegates](#delegate-response-types) do. diff --git a/mkdocs/docs/en/examples/hello-world.md b/mkdocs/docs/en/examples/hello-world.md index 4a4ec6c..9aa7201 100644 --- a/mkdocs/docs/en/examples/hello-world.md +++ b/mkdocs/docs/en/examples/hello-world.md @@ -54,7 +54,7 @@ Basic concepts and description of the framework can be read on the [main page](. } dependencies { - koraBom platform("ru.tinkoff.kora:kora-parent:1.2.18") + koraBom platform("ru.tinkoff.kora:kora-parent:1.2.19") annotationProcessor "ru.tinkoff.kora:annotation-processors" implementation "ru.tinkoff.kora:http-server-undertow" @@ -91,7 +91,7 @@ Basic concepts and description of the framework can be read on the [main page](. } dependencies { - koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.19")) ksp("ru.tinkoff.kora:symbol-processors") implementation("ru.tinkoff.kora:http-server-undertow") diff --git a/mkdocs/docs/en/guides/getting-started.md b/mkdocs/docs/en/guides/getting-started.md index bc1f87e..d7b17dc 100644 --- a/mkdocs/docs/en/guides/getting-started.md +++ b/mkdocs/docs/en/guides/getting-started.md @@ -491,7 +491,7 @@ Now add dependencies. First import the Kora BOM. After this line, Kora dependenc ```groovy dependencies { - koraBom platform("ru.tinkoff.kora:kora-parent:1.2.18") + koraBom platform("ru.tinkoff.kora:kora-parent:1.2.19") annotationProcessor "ru.tinkoff.kora:annotation-processors" @@ -506,7 +506,7 @@ Now add dependencies. First import the Kora BOM. After this line, Kora dependenc ```kotlin dependencies { - koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.19")) ksp("ru.tinkoff.kora:symbol-processor") diff --git a/mkdocs/docs/ru/changelog/changelog.md b/mkdocs/docs/ru/changelog/changelog.md index c4e5860..c48ce0b 100644 --- a/mkdocs/docs/ru/changelog/changelog.md +++ b/mkdocs/docs/ru/changelog/changelog.md @@ -5,7 +5,21 @@ hide: - navigation --- -## 1.2.18 +## 1.2.19 + +Исправлено: + +- Исправлено строгое сопоставление тегов перехватчиков в KSP +- Исправлена обработка `multipart byte` полей в генераторе OpenAPI +- Исправлено создание компонента `SchedulingLogger` и корректные уровни логирования +- Исправлено применение `advanced.coalescer.rescheduleInterval` к драйверу Cassandra +- Исправлен потенциальный NPE тегов телеметрии HTTP Client на неопределённых хостах +- Исправлен понижение Jackson до 2.19.4 из-за зависимостей Kotlin `2.x`+ через BOM +- Исправлена ссылка на предикат повторителя по умолчанию в Javadoc `RetryConfig` +- Исправлен Javadoc для классов конфигурации из документации +- Обновлена аннотация кэша: время хранения изменено с `class` на `runtime` + +### 1.2.18 Добавлено: diff --git a/mkdocs/docs/ru/documentation/general.md b/mkdocs/docs/ru/documentation/general.md index b408723..9031924 100644 --- a/mkdocs/docs/ru/documentation/general.md +++ b/mkdocs/docs/ru/documentation/general.md @@ -139,8 +139,8 @@ Kora рассчитана на сборку через [Gradle](https://gradle.o } dependencies { - annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.18" - implementation(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.19" + implementation(platform("ru.tinkoff.kora:kora-parent:1.2.19")) } ``` @@ -166,8 +166,8 @@ Kora рассчитана на сборку через [Gradle](https://gradle.o } dependencies { - ksp("ru.tinkoff.kora:symbol-processors:1.2.18") - implementation(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + ksp("ru.tinkoff.kora:symbol-processors:1.2.19") + implementation(platform("ru.tinkoff.kora:kora-parent:1.2.19")) } ``` @@ -200,8 +200,8 @@ Kora рассчитана на сборку через [Gradle](https://gradle.o ```groovy dependencies { - annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.18" - implementation(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + annotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.19" + implementation(platform("ru.tinkoff.kora:kora-parent:1.2.19")) } ``` @@ -211,8 +211,8 @@ Kora рассчитана на сборку через [Gradle](https://gradle.o ```kotlin dependencies { - ksp("ru.tinkoff.kora:symbol-processors:1.2.18") - implementation(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + ksp("ru.tinkoff.kora:symbol-processors:1.2.19") + implementation(platform("ru.tinkoff.kora:kora-parent:1.2.19")) } ``` diff --git a/mkdocs/docs/ru/documentation/junit5.md b/mkdocs/docs/ru/documentation/junit5.md index a5c9f05..de2d8e7 100644 --- a/mkdocs/docs/ru/documentation/junit5.md +++ b/mkdocs/docs/ru/documentation/junit5.md @@ -678,7 +678,7 @@ agent: ```groovy dependencies { - testAnnotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.18" + testAnnotationProcessor "ru.tinkoff.kora:annotation-processors:1.2.19" } ``` @@ -688,7 +688,7 @@ agent: ```groovy dependencies { - kspTest("ru.tinkoff.kora:symbol-processors:1.2.18") + kspTest("ru.tinkoff.kora:symbol-processors:1.2.19") } ``` diff --git a/mkdocs/docs/ru/documentation/openapi-codegen.md b/mkdocs/docs/ru/documentation/openapi-codegen.md index 0c75438..8f9f0b2 100644 --- a/mkdocs/docs/ru/documentation/openapi-codegen.md +++ b/mkdocs/docs/ru/documentation/openapi-codegen.md @@ -1,7 +1,7 @@ --- description: "Explains Kora OpenAPI code generation for HTTP clients and servers, generator options, tags, validation, interceptors, authorization, and JsonNullable support. Use when working with openapi-generator, @HttpClient, @HttpController, @InterceptWith, @Tag, @Validate, JsonNullable, primaryAuth, prefixPath, requestInDelegateParams, HttpClientTokenProvider, PrincipalWithScopes, ApiSecurity." agent: - use_when: "Use this file for Kora docs or implementation questions about Kora OpenAPI code generation for HTTP clients and servers, generator options, tags, validation, interceptors, authorization, and JsonNullable support; key triggers include openapi-generator, @HttpClient, @HttpController, @InterceptWith, @Tag, @Validate, JsonNullable, primaryAuth, prefixPath, requestInDelegateParams, HttpClientTokenProvider, PrincipalWithScopes, ApiSecurity." + use_when: "Use this file for Kora docs or implementation questions about Kora OpenAPI code generation for HTTP clients and servers, generator options, tags, validation, interceptors, authorization, and JsonNullable support; key triggers include openapi-generator, @HttpClient, @HttpController, @InterceptWith, @Tag, @Validate, JsonNullable, primaryAuth, prefixPath, requestInDelegateParams, HttpClientTokenProvider, PrincipalWithScopes, ApiSecurity." --- Этот модуль генерирует код Kora из контракта `OpenAPI` с помощью [OpenAPI Generator](https://openapi-generator.tech/docs/plugins#gradle). @@ -9,7 +9,8 @@ agent: а также модели запросов и ответов, мапперы, обработку авторизации и дополнительные аннотации. Такой подход полезен, когда `OpenAPI` является источником истины для транспортного контракта, а код приложения должен автоматически ему следовать. -Если нужен пошаговый разбор перед справочным описанием, смотрите [OpenAPI HTTP-сервер](../guides/openapi-http-server.md), [продвинутый OpenAPI HTTP-сервер](../guides/openapi-http-server-advanced.md) и [OpenAPI HTTP-клиент](../guides/openapi-http-client.md). +Если нужен пошаговый разбор перед справочным описанием, смотрите [OpenAPI HTTP-сервер](../guides/openapi-http-server.md), [продвинутый OpenAPI HTTP-сервер](../guides/openapi-http-server-advanced.md) +и [OpenAPI HTTP-клиент](../guides/openapi-http-client.md). ## Подключение { #dependency } @@ -19,7 +20,7 @@ agent: ```groovy buildscript { dependencies { - classpath("ru.tinkoff.kora:openapi-generator:1.2.18") + classpath("ru.tinkoff.kora:openapi-generator:1.2.19") } } ``` @@ -39,7 +40,7 @@ agent: ```groovy buildscript { dependencies { - classpath("ru.tinkoff.kora:openapi-generator:1.2.18") + classpath("ru.tinkoff.kora:openapi-generator:1.2.19") } } ``` @@ -69,22 +70,22 @@ agent: Они определяют, откуда читать контракт, куда помещать сгенерированные файлы, какие пакеты использовать и как предобрабатывать описание `OpenAPI`. В проектах Kora эти параметры обычно задаются явно, поскольку сгенерированный код затем добавляется в обычную компиляцию проекта. -| Параметр | Описание | -| -------- | -------- | -| `generatorName` | Имя генератора (`обязательный`, без значения по умолчанию). Для Kora всегда указывайте `kora`. | -| `inputSpec` | Путь к файлу `OpenAPI` (`обязательный`, без значения по умолчанию). Обычно это файл в `src/main/resources/openapi`, например `$projectDir/src/main/resources/openapi/openapi.yaml`. | -| `outputDir` | Каталог для сгенерированных файлов (по умолчанию не указан, необязательный). В проектах Kora это обычно каталог в `build`, например `$buildDir/generated/openapi`, который добавляется в основной набор исходного кода (source set). | -| `apiPackage` | Пакет для сгенерированных интерфейсов API, контроллеров, классов `delegate` и мапперов (по умолчанию: `org.openapitools.api`). Рекомендуется указывать его явно, например `ru.tinkoff.kora.example.openapi.api`. | -| `modelPackage` | Пакет для моделей, сгенерированных из схем `OpenAPI` (по умолчанию: `org.openapitools.model`). Рекомендуется указывать его явно, например `ru.tinkoff.kora.example.openapi.model`. | -| `invokerPackage` | Вспомогательный пакет генератора (по умолчанию: `org.openapitools.api`). Рекомендуется указывать его явно рядом с `apiPackage` и `modelPackage`, например `ru.tinkoff.kora.example.openapi.invoker`. | -| `configOptions` | Специфичные для генератора параметры (по умолчанию: `{}`). Для Kora здесь задаются `mode`, `clientConfigPrefix`, `enableServerValidation`, `interceptors` и другие параметры, описанные ниже. | -| `globalProperties` | Ограничивает, какие сущности генерируются (по умолчанию: `{}`). Полезно, когда нужно сгенерировать только `apis`, только `models` или отдельные модели и операции. Используйте осторожно: обычным клиентам и серверам Kora, как правило, нужны классы API, модели и мапперы вместе. | -| `openapiNormalizer` | Предобрабатывает контракт `OpenAPI` перед генерацией (по умолчанию: `{}`). Часто используется, чтобы отключить стандартные преобразования через `DISABLE_ALL`, сгенерировать только выбранные операции через `FILTER` или управлять правилами вроде `SIMPLIFY_ONEOF_ANYOF`. | -| `importMappings` | Сопоставляет имя схемы с существующим классом (по умолчанию: `{}`). Полезно, когда модель написана вручную или приходит из другого модуля, например `Money: "com.example.Money"`. | -| `typeMappings` | Сопоставляет тип `OpenAPI Generator` с типом языка (по умолчанию: `{}`). Используется для точечной замены типов, например замены `OffsetDateTime` на специфичный для проекта тип времени. | -| `schemaMappings` | Сопоставляет схему `OpenAPI` с внешним типом без генерации модели (по умолчанию: `{}`). Аналогично `importMappings`, но настраивается на уровне схемы и полезно для переиспользования общих DTO. | -| `skipValidateSpec` | Пропускает валидацию контракта `OpenAPI` перед генерацией (по умолчанию: `false`). В обычных сборках валидацию лучше оставлять включённой; используйте `true` только временно для внешних контрактов, которые нельзя быстро исправить. | -| `cleanupOutput` | Очищает `outputDir` перед генерацией (по умолчанию: `false`). Полезно, когда контракт часто меняется и файлы удалённых операций или моделей должны исчезать. Не указывайте в `outputDir` каталог с написанным вручную кодом. | +| Параметр | Описание | +|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `generatorName` | Имя генератора (`обязательный`, без значения по умолчанию). Для Kora всегда указывайте `kora`. | +| `inputSpec` | Путь к файлу `OpenAPI` (`обязательный`, без значения по умолчанию). Обычно это файл в `src/main/resources/openapi`, например `$projectDir/src/main/resources/openapi/openapi.yaml`. | +| `outputDir` | Каталог для сгенерированных файлов (по умолчанию не указан, необязательный). В проектах Kora это обычно каталог в `build`, например `$buildDir/generated/openapi`, который добавляется в основной набор исходного кода (source set). | +| `apiPackage` | Пакет для сгенерированных интерфейсов API, контроллеров, классов `delegate` и мапперов (по умолчанию: `org.openapitools.api`). Рекомендуется указывать его явно, например `ru.tinkoff.kora.example.openapi.api`. | +| `modelPackage` | Пакет для моделей, сгенерированных из схем `OpenAPI` (по умолчанию: `org.openapitools.model`). Рекомендуется указывать его явно, например `ru.tinkoff.kora.example.openapi.model`. | +| `invokerPackage` | Вспомогательный пакет генератора (по умолчанию: `org.openapitools.api`). Рекомендуется указывать его явно рядом с `apiPackage` и `modelPackage`, например `ru.tinkoff.kora.example.openapi.invoker`. | +| `configOptions` | Специфичные для генератора параметры (по умолчанию: `{}`). Для Kora здесь задаются `mode`, `clientConfigPrefix`, `enableServerValidation`, `interceptors` и другие параметры, описанные ниже. | +| `globalProperties` | Ограничивает, какие сущности генерируются (по умолчанию: `{}`). Полезно, когда нужно сгенерировать только `apis`, только `models` или отдельные модели и операции. Используйте осторожно: обычным клиентам и серверам Kora, как правило, нужны классы API, модели и мапперы вместе. | +| `openapiNormalizer` | Предобрабатывает контракт `OpenAPI` перед генерацией (по умолчанию: `{}`). Часто используется, чтобы отключить стандартные преобразования через `DISABLE_ALL`, сгенерировать только выбранные операции через `FILTER` или управлять правилами вроде `SIMPLIFY_ONEOF_ANYOF`. | +| `importMappings` | Сопоставляет имя схемы с существующим классом (по умолчанию: `{}`). Полезно, когда модель написана вручную или приходит из другого модуля, например `Money: "com.example.Money"`. | +| `typeMappings` | Сопоставляет тип `OpenAPI Generator` с типом языка (по умолчанию: `{}`). Используется для точечной замены типов, например замены `OffsetDateTime` на специфичный для проекта тип времени. | +| `schemaMappings` | Сопоставляет схему `OpenAPI` с внешним типом без генерации модели (по умолчанию: `{}`). Аналогично `importMappings`, но настраивается на уровне схемы и полезно для переиспользования общих DTO. | +| `skipValidateSpec` | Пропускает валидацию контракта `OpenAPI` перед генерацией (по умолчанию: `false`). В обычных сборках валидацию лучше оставлять включённой; используйте `true` только временно для внешних контрактов, которые нельзя быстро исправить. | +| `cleanupOutput` | Очищает `outputDir` перед генерацией (по умолчанию: `false`). Полезно, когда контракт часто меняется и файлы удалённых операций или моделей должны исчезать. Не указывайте в `outputDir` каталог с написанным вручную кодом. | Пример с общими параметрами: @@ -169,25 +170,25 @@ agent: `openapiNormalizer` изменяет входной контракт `OpenAPI` перед генерацией. Это не параметр Kora, а общий механизм `OpenAPI Generator`. Для Kora он особенно полезен, когда один большой контракт используется несколькими приложениями или когда контракт содержит неоднозначные для генерации кода конструкции. -| Правило | Описание | -| -------- | -------- | -| `DISABLE_ALL` | Отключает стандартные правила нормализации (по умолчанию: `false`). Начиная с `OpenAPI Generator 7` некоторые правила включены по умолчанию, поэтому предсказуемая генерация часто начинается с `DISABLE_ALL: "true"`, а затем явно включаются только нужные правила. | -| `FILTER` | Оставляет для генерации только выбранные операции (по умолчанию не указано, необязательно). Поддерживает один фильтр за раз: `operationId:name1\|name2`, `method:get\|post` или `tag:public\|billing`. Операции, которые не подходят, помечаются как `x-internal: true` и не генерируются. | -| `KEEP_ONLY_FIRST_TAG_IN_OPERATION` | Оставляет у операции только первый тег (по умолчанию: `false`). Полезно, когда у операций несколько тегов и они разбиваются на несколько классов API не так, как вы ожидаете. | -| `SET_TAGS_FOR_ALL_OPERATIONS` | Заменяет теги всех операций одним переданным значением (по умолчанию не указано, необязательно). Полезно, когда нужно принудительно получить один сгенерированный класс API. | -| `SET_TAGS_TO_OPERATIONID` | Устанавливает тег операции равным `operationId`, либо `default`, если `operationId` пуст (по умолчанию: `false`). Полезно для контрактов без пригодных тегов, когда нужна предсказуемая группировка операций. | -| `SET_TAGS_TO_VENDOR_EXTENSION` | Читает теги операций из указанного расширения, например `x-tags` (по умолчанию не указано, необязательно). Полезно, когда внешний контракт нельзя изменить, но в нём уже есть собственная группировка операций. | -| `FIX_DUPLICATED_OPERATIONID` | Добавляет числовой суффикс к повторяющимся значениям `operationId` (по умолчанию: `false`). Лучше исправить контракт, но это правило помогает временно сгенерировать код по внешнему описанию. | -| `SET_BEARER_AUTH_FOR_NAME` | Преобразует указанную схему безопасности в `bearerAuth` (по умолчанию не указано, необязательно). Полезно для внешних контрактов, где bearer-токен описан нестандартно, но в приложении его нужно обрабатывать как обычную схему bearer. | -| `REF_AS_PARENT_IN_ALLOF` | Помечает `$ref` внутри `allOf` как родительскую схему через `x-parent: true` (по умолчанию: `false`). Может помочь контрактам, которые моделируют наследование через `allOf`. | -| `SIMPLIFY_ONEOF_ANYOF` | Упрощает некоторые конструкции `oneOf`/`anyOf`, например переносит вариант `null` в `nullable: true` и убирает одиночные обёртки (включено по умолчанию в `OpenAPI Generator 7`, если не задан `DISABLE_ALL`). Для Kora это может менять форму сгенерированных моделей, поэтому включайте его осознанно. | -| `SIMPLIFY_ANYOF_STRING_AND_ENUM_STRING` | Упрощает `anyOf`, составленный из `string` и строкового перечисления, до `string` (по умолчанию: `false`). Это может помочь с контрактами, где ограничение перечисления не важно для кода. | -| `SIMPLIFY_BOOLEAN_ENUM` | Преобразует булево перечисление в обычный `boolean` (включено по умолчанию в `OpenAPI Generator 7`, если не задан `DISABLE_ALL`). | -| `REFACTOR_ALLOF_WITH_PROPERTIES_ONLY` | Переносит свойства из схемы, содержащей одновременно `allOf` и `properties`, в отдельную схему внутри `allOf` (включено по умолчанию в `OpenAPI Generator 7`, если не задан `DISABLE_ALL`). Это может помочь наследованию, но строгие контракты стоит проверять после генерации. | -| `NORMALIZE_31SPEC` | Нормализует некоторые конструкции `OpenAPI 3.1` в форму, которую генератор понимает лучше (по умолчанию: `false`). Полезно для контрактов `3.1`, когда генерация не удаётся на новых формах схем. | -| `REMOVE_X_INTERNAL` | Удаляет `x-internal: true` из операций и моделей (по умолчанию: `false`). Используйте, только когда контракт уже содержит `x-internal`, но конкретная задача генерации должна принудительно вернуть такие операции. | -| `SET_CONTAINER_TO_NULLABLE` | Помечает типы-контейнеры `array`, `set` или `map` как `nullable` (по умолчанию не указано, необязательно). Используйте, только когда во внешнем контракте систематически отсутствует `nullable` у таких полей. | -| `SET_PRIMITIVE_TYPES_TO_NULLABLE` | Помечает примитивные типы `string`, `integer`, `number` или `boolean` как `nullable` (по умолчанию не указано, необязательно). Это существенно меняет сигнатуры моделей, поэтому применяйте его только к проблемным внешним контрактам. | +| Правило | Описание | +|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `DISABLE_ALL` | Отключает стандартные правила нормализации (по умолчанию: `false`). Начиная с `OpenAPI Generator 7` некоторые правила включены по умолчанию, поэтому предсказуемая генерация часто начинается с `DISABLE_ALL: "true"`, а затем явно включаются только нужные правила. | +| `FILTER` | Оставляет для генерации только выбранные операции (по умолчанию не указано, необязательно). Поддерживает один фильтр за раз: `operationId:name1\|name2`, `method:get\|post` или `tag:public\|billing`. Операции, которые не подходят, помечаются как `x-internal: true` и не генерируются. | +| `KEEP_ONLY_FIRST_TAG_IN_OPERATION` | Оставляет у операции только первый тег (по умолчанию: `false`). Полезно, когда у операций несколько тегов и они разбиваются на несколько классов API не так, как вы ожидаете. | +| `SET_TAGS_FOR_ALL_OPERATIONS` | Заменяет теги всех операций одним переданным значением (по умолчанию не указано, необязательно). Полезно, когда нужно принудительно получить один сгенерированный класс API. | +| `SET_TAGS_TO_OPERATIONID` | Устанавливает тег операции равным `operationId`, либо `default`, если `operationId` пуст (по умолчанию: `false`). Полезно для контрактов без пригодных тегов, когда нужна предсказуемая группировка операций. | +| `SET_TAGS_TO_VENDOR_EXTENSION` | Читает теги операций из указанного расширения, например `x-tags` (по умолчанию не указано, необязательно). Полезно, когда внешний контракт нельзя изменить, но в нём уже есть собственная группировка операций. | +| `FIX_DUPLICATED_OPERATIONID` | Добавляет числовой суффикс к повторяющимся значениям `operationId` (по умолчанию: `false`). Лучше исправить контракт, но это правило помогает временно сгенерировать код по внешнему описанию. | +| `SET_BEARER_AUTH_FOR_NAME` | Преобразует указанную схему безопасности в `bearerAuth` (по умолчанию не указано, необязательно). Полезно для внешних контрактов, где bearer-токен описан нестандартно, но в приложении его нужно обрабатывать как обычную схему bearer. | +| `REF_AS_PARENT_IN_ALLOF` | Помечает `$ref` внутри `allOf` как родительскую схему через `x-parent: true` (по умолчанию: `false`). Может помочь контрактам, которые моделируют наследование через `allOf`. | +| `SIMPLIFY_ONEOF_ANYOF` | Упрощает некоторые конструкции `oneOf`/`anyOf`, например переносит вариант `null` в `nullable: true` и убирает одиночные обёртки (включено по умолчанию в `OpenAPI Generator 7`, если не задан `DISABLE_ALL`). Для Kora это может менять форму сгенерированных моделей, поэтому включайте его осознанно. | +| `SIMPLIFY_ANYOF_STRING_AND_ENUM_STRING` | Упрощает `anyOf`, составленный из `string` и строкового перечисления, до `string` (по умолчанию: `false`). Это может помочь с контрактами, где ограничение перечисления не важно для кода. | +| `SIMPLIFY_BOOLEAN_ENUM` | Преобразует булево перечисление в обычный `boolean` (включено по умолчанию в `OpenAPI Generator 7`, если не задан `DISABLE_ALL`). | +| `REFACTOR_ALLOF_WITH_PROPERTIES_ONLY` | Переносит свойства из схемы, содержащей одновременно `allOf` и `properties`, в отдельную схему внутри `allOf` (включено по умолчанию в `OpenAPI Generator 7`, если не задан `DISABLE_ALL`). Это может помочь наследованию, но строгие контракты стоит проверять после генерации. | +| `NORMALIZE_31SPEC` | Нормализует некоторые конструкции `OpenAPI 3.1` в форму, которую генератор понимает лучше (по умолчанию: `false`). Полезно для контрактов `3.1`, когда генерация не удаётся на новых формах схем. | +| `REMOVE_X_INTERNAL` | Удаляет `x-internal: true` из операций и моделей (по умолчанию: `false`). Используйте, только когда контракт уже содержит `x-internal`, но конкретная задача генерации должна принудительно вернуть такие операции. | +| `SET_CONTAINER_TO_NULLABLE` | Помечает типы-контейнеры `array`, `set` или `map` как `nullable` (по умолчанию не указано, необязательно). Используйте, только когда во внешнем контракте систематически отсутствует `nullable` у таких полей. | +| `SET_PRIMITIVE_TYPES_TO_NULLABLE` | Помечает примитивные типы `string`, `integer`, `number` или `boolean` как `nullable` (по умолчанию не указано, необязательно). Это существенно меняет сигнатуры моделей, поэтому применяйте его только к проблемным внешним контрактам. | Пример генерации только публичной части контракта: @@ -247,15 +248,15 @@ agent: Kora также поддерживает несколько `configOptions`, управляющих мапперами `JSON` и общей генерацией моделей. Они не зависят от того, генерируется клиент или сервер. -| Параметр | Описание | -| -------- | -------- | -| `jsonAnnotation` | Аннотация-тег, используемая для внедрения мапперов `JSON` в сгенерированные мапперы запросов и ответов (по умолчанию: `ru.tinkoff.kora.json.common.annotation.Json`). | -| `objectType` | Тип для схем `type: object` без более точного описания. `Java` по умолчанию использует `java.lang.Object`, а `Kotlin` — `kotlin.Any`. Например, укажите `com.fasterxml.jackson.databind.JsonNode`, если приложение хочет обрабатывать произвольный `JSON` как дерево. | -| `disableHtmlEscaping` | Отключает экранирование HTML-символов в строках `JSON` (по умолчанию: `false`). Обычно значение по умолчанию оставляют. | -| `ignoreAnyOfInEnum` | Игнорирует `anyOf` при генерации перечислений (по умолчанию: `false`). Может помочь с контрактами, где перечисление описано через смешанные конструкции `anyOf`. | -| `discriminatorCaseSensitive` | Управляет чувствительностью к регистру при поиске значения дискриминатора для полиморфных (`oneOf`) моделей с дискриминатором (по умолчанию: `true`). Установите `false`, когда входящие значения дискриминатора могут отличаться регистром от определения в схеме. | -| `additionalModelTypeAnnotations` | Дополнительные аннотации на типах моделей (по умолчанию не указано, необязательно). Несколько аннотаций разделяются `;`, например `@Deprecated;@MyAnnotation`. | -| `additionalEnumTypeAnnotations` | Дополнительные аннотации на типах перечислений (по умолчанию не указано, необязательно). Несколько аннотаций разделяются `;`. | +| Параметр | Описание | +|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `jsonAnnotation` | Аннотация-тег, используемая для внедрения мапперов `JSON` в сгенерированные мапперы запросов и ответов (по умолчанию: `ru.tinkoff.kora.json.common.annotation.Json`). | +| `objectType` | Тип для схем `type: object` без более точного описания. `Java` по умолчанию использует `java.lang.Object`, а `Kotlin` — `kotlin.Any`. Например, укажите `com.fasterxml.jackson.databind.JsonNode`, если приложение хочет обрабатывать произвольный `JSON` как дерево. | +| `disableHtmlEscaping` | Отключает экранирование HTML-символов в строках `JSON` (по умолчанию: `false`). Обычно значение по умолчанию оставляют. | +| `ignoreAnyOfInEnum` | Игнорирует `anyOf` при генерации перечислений (по умолчанию: `false`). Может помочь с контрактами, где перечисление описано через смешанные конструкции `anyOf`. | +| `discriminatorCaseSensitive` | Управляет чувствительностью к регистру при поиске значения дискриминатора для полиморфных (`oneOf`) моделей с дискриминатором (по умолчанию: `true`). Установите `false`, когда входящие значения дискриминатора могут отличаться регистром от определения в схеме. | +| `additionalModelTypeAnnotations` | Дополнительные аннотации на типах моделей (по умолчанию не указано, необязательно). Несколько аннотаций разделяются `;`, например `@Deprecated;@MyAnnotation`. | +| `additionalEnumTypeAnnotations` | Дополнительные аннотации на типах перечислений (по умолчанию не указано, необязательно). Несколько аннотаций разделяются `;`. | Пример: @@ -507,13 +508,13 @@ Kora также поддерживает несколько `configOptions`, у Сигнатуры методов клиента зависят от выбранного `mode`: -| Режим | Пример возвращаемого типа | -| -------- | -------- | -| `java-client` | `PetApiResponses.GetPetByIdApiResponse` (блокирующее значение) | -| `java-async-client` | `CompletionStage` | -| `java-reactive-client` | `Mono` (требует `reactor-core`) | -| `kotlin-client` | `PetApiResponses.GetPetByIdApiResponse` (блокирующее значение) | -| `kotlin-suspend-client` | `suspend fun ...: PetApiResponses.GetPetByIdApiResponse` | +| Режим | Пример возвращаемого типа | +|-------------------------|------------------------------------------------------------------------| +| `java-client` | `PetApiResponses.GetPetByIdApiResponse` (блокирующее значение) | +| `java-async-client` | `CompletionStage` | +| `java-reactive-client` | `Mono` (требует `reactor-core`) | +| `kotlin-client` | `PetApiResponses.GetPetByIdApiResponse` (блокирующее значение) | +| `kotlin-suspend-client` | `suspend fun ...: PetApiResponses.GetPetByIdApiResponse` | Каждый метод возвращает запечатанную (`sealed`) обёртку `*ApiResponses`, подтипы которой кодируют HTTP-статус, так же как это делают [делегаты сервера](#delegate-response-types). diff --git a/mkdocs/docs/ru/examples/hello-world.md b/mkdocs/docs/ru/examples/hello-world.md index 42c9ae4..091fb75 100644 --- a/mkdocs/docs/ru/examples/hello-world.md +++ b/mkdocs/docs/ru/examples/hello-world.md @@ -54,7 +54,7 @@ distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip } dependencies { - koraBom platform("ru.tinkoff.kora:kora-parent:1.2.18") + koraBom platform("ru.tinkoff.kora:kora-parent:1.2.19") annotationProcessor "ru.tinkoff.kora:annotation-processors" implementation "ru.tinkoff.kora:http-server-undertow" @@ -91,7 +91,7 @@ distributionUrl=https\://services.gradle.org/distributions/gradle-8.10-bin.zip } dependencies { - koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.19")) ksp("ru.tinkoff.kora:symbol-processors") implementation("ru.tinkoff.kora:http-server-undertow") diff --git a/mkdocs/docs/ru/guides/getting-started.md b/mkdocs/docs/ru/guides/getting-started.md index b635705..f7ea924 100644 --- a/mkdocs/docs/ru/guides/getting-started.md +++ b/mkdocs/docs/ru/guides/getting-started.md @@ -494,7 +494,7 @@ Kora состоит из нескольких модулей. Чтобы не у ```groovy dependencies { - koraBom platform("ru.tinkoff.kora:kora-parent:1.2.18") + koraBom platform("ru.tinkoff.kora:kora-parent:1.2.19") annotationProcessor "ru.tinkoff.kora:annotation-processors" @@ -509,7 +509,7 @@ Kora состоит из нескольких модулей. Чтобы не у ```kotlin dependencies { - koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.18")) + koraBom(platform("ru.tinkoff.kora:kora-parent:1.2.19")) ksp("ru.tinkoff.kora:symbol-processor")