[KOTLIN-ALL-GENS] - fix escaping of values across all templates

Draft
PI
1mo ago
+4130-944

This PR fixes many issues with incorrect escaping of default values, examples, descriptions in various contexts (as string literals, as kdocs, as multiline docs, as single line docs, as inline docs). The biggest issue of these was the default value that practically affects implementation logic and it was often incorrectly escaped. E.g. $ symbol was sometimes escaped as dollar, sometimes it was not escaped at all, leading to issues with compilation.

commits until https://github.com/OpenAPITools/openapi-generator/pull/23633/changes/e14fdba77dafb68fdcc6915ac94d4af583f57c74 apply the fix to the existing sample configs as-is. The next commit includes a stress-test for the generated samples on purpose by extending the various open api specs with difficult-to-process values full of tricky defaults/examples/descriptions as well as problematic attribute names.

I am not 100% sure that this fixes everything everywhere, but I think it is a move in the right direction for the kotlin codegens

PR checklist

  • Read the contribution guidelines.
  • Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
  • Run the following to build the project and update samples: 
    ./mvnw clean package || exit
./bin/generate-samples.sh ./bin/configs/*.yaml || exit
./bin/utils/export_docs_generators.sh || exit
    (For Windows users, please run the script in WSL)
    Commit all changed files.
    This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
    These must match the expectations made by your contribution.
    You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
    IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
  • File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
  • If your PR solves a reported issue, reference it using GitHub's linking syntax (e.g., having "fixes #123" present in the PR description)
  • If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

Summary by cubic

Fixes incorrect escaping across all Kotlin templates to prevent invalid Kotlin code, broken docs, and injection via triple-quoted strings. Adds Kotlin/Markdown escaping lambdas, updates clients/servers (Spring, JAX‑RS, Javalin, Misk, Ktor, Retrofit2, Volley, WireMock), expands tests, and regenerates samples (fixes #20502).

  • Bug Fixes

    • Add lambda.escapeInNormalString, lambda.escapeDollarInMultiline, lambda.escapeMarkdown, and lambda.removeLineBreak; use them in annotations, paths, param/base names, headers/cookies, WireMock URLs/models, and Markdown docs.
    • Replace Kotlin Spring annotation triple‑quoted strings with escaped normal strings to prevent code injection; escape summaries/descriptions, ApiResponse messages, and examples.
    • Correct string defaults via new unescapedDefaultValue; apply to params, model properties, annotation defaults, and @DefaultValue (handles enums; avoids unsafe triple‑quoted strings).
    • Add unescaped fields for templates: CodegenOperation.unescapedSummary, CodegenResponse.unescapedMessage, CodegenParameter.unescapedDefaultValue, CodegenProperty.unescapedDefaultValue.
    • kotlin-jvm-retrofit2: sanitize invalid @Path names to [a-zA-Z][a-zA-Z0-9_-]* via vendorExtensions.x-retrofit-path-name; escape path strings and param/header/query names in annotations; keep generateOneOfAnyOfWrappers with gson in ApiClient.kt secondary constructor.
    • Kotlin Spring/JAX‑RS/Javalin/Misk: use escaped baseName in @JsonProperty; escape implicit header names/descriptions; normalize parameter tables in generated docs.
    • Clients (OkHttp, WebClient, RestClient, Ktor, Volley): escape map keys and annotation literals; use unescapedDefaultValue for string defaults; escape Ktor query keys.
    • WireMock: escape path templates, parameter names, JSON property defaults, and annotation strings.
    • Tests/samples: add worst‑case spec and $ path/query cases; new tests for Retrofit2 path‑name sanitization, Jackson @JsonProperty, Kotlin Spring multi‑line description handling, and Ktor query key escaping; migrate legacy tests; add echo_api sample files; update Misk sample config.

  • Migration

    • For custom templates, use {{#lambda.escapeInNormalString}}...{{/lambda.escapeInNormalString}}, {{#lambda.escapeDollarInMultiline}}...{{/lambda.escapeDollarInMultiline}}, {{#lambda.escapeMarkdown}}...{{/lambda.escapeMarkdown}}, and {{#lambda.removeLineBreak}}...{{/lambda.removeLineBreak}}. Replace old keys like lambdaEscapeInNormalString / lambdaRemoveLineBreak. Regenerate code.