Stream example rendering to avoid OOM for large specs by wilx · Pull Request #24160 · OpenAPITools/openapi-generator

wilx · 2026-06-29T19:14:32Z

This PR fixes the OOM/memory pressure reported in #23849 by changing example and OpenAPI spec rendering to stream through the templating engine instead of materializing large rendered strings up front.

This is likely a major-version change. The template-facing example rendering contract changes from using pre-rendered string values such as example, modelJson, openapi-json, and openapi-yaml in many places to using writer-backed lambdas such as lambdaExample, lambdaModelJson, lambdaOpenapiJson, and lambdaOpenapiYaml. Because custom templates may reference the old values directly, this can break existing custom templates and should be treated as a backwards-incompatible template API change.

The main change is in the core templating/example rendering path:

add writer-based template rendering support
render generated examples, model JSON, and OpenAPI JSON/YAML through mustache lambdas
update generator templates to consume the streamed example/spec output

This also includes related fixes found while applying the streaming path across generators, including JetBrains .http request example rendering/content-type handling and Java generator example rendering updates.

Samples, docs, and site output have been regenerated.

All tests were run.

PR checklist

Read the contribution guidelines.

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

Commit all changed files.

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

Streams example and OpenAPI spec rendering end-to-end to prevent OOM on large specs by writing through Mustache writer APIs directly to files. Keeps scalar examples as plain text in annotations while streaming object/array examples as JSON.

Bug Fixes
- Streaming template path: added writeTemplate to the templating engine, atomic writes via unique temp files, and minimal-update file comparisons.
- New output lambdas: lambdaExample, lambdaModelJson, lambdaOpenapiJson, lambdaOpenapiYaml; updated templates across generators (incl. annotations) and rendered GraphQL examples as typed literals.
- Streaming-safe escaping: newline, HTML, double-quote, Java/Kotlin/JSON string lambdas; Kotlin Spring now uses streaming lambdas; templating docs add escapeJavaString and escapeJsonString.
- Examples support non-string values: arrays/objects stream as JSON; scalars render as text to avoid extra quotes in string attributes. Snapshot model JSON before later schema mutation. Include JSON examples in parameter/property equality but omit from hashCode.
- JetBrains .http requests: per-media-type examples, content-type filtering, deduplication, and omission of value-less examples.
- Generators now use the parameter example setter to keep streamed JSON example state in sync.
- Tests: JSON output comparisons are line-ending neutral; added a Spring regression test for [BUG] OutOfMemeoryError: Java heap space - Potential memory leak? #23849 (temporarily disabled the OOM test).
Migration
- Breaking template API: replace {{{example}}}, {{{modelJson}}}, {{{openapi-json}}}, {{{openapi-yaml}}} with {{#lambdaExample}}{{/lambdaExample}}, {{#lambdaModelJson}}{{/lambdaModelJson}}, {{#lambdaOpenapiJson}}{{/lambdaOpenapiJson}}, {{#lambdaOpenapiYaml}}{{/lambdaOpenapiYaml}}.
- If custom templates assumed example strings, update to use the new lambdas or handle non-string values.

^{Written for commit 39145da. Summary will update on new commits.}

cubic-dev-ai

20 issues found and verified against the latest diff