[CORE] - Feature: forcedGenerateSchemas — Force generation of schema-mapped or import-mapped schemas

[Picazsoo]

When a schema is listed in schemaMappings, OpenAPI Generator skips it entirely during model generation (no file is written). This is correct for normal use, but makes it impossible to generate a "reference copy" of the schema - e.g. for a test that asserts a hand-written enum class has not diverged from what the generator would produce.

This feature adds a forcedGenerateSchemas option: a set of schema names that must be generated even when they also appear in schemaMappings or importMappings. It is also possible to just pass an asterisk * in the list to force generation of all schemas.

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
  

  (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.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

[cubic-dev-ai]

1 issue found across 14 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Mattias-Sehlstedt]

Would the behavior that you seek not simply be realized by generating the entire structure without any schema-mappings, creating a git-branch with it, and then doing it with the schema-mappings, and then looking at the diffs?

Having a setting dedicated to it feels a bit overkill and feature-for-the-sake-of-feature?

[Picazsoo]

Hi @Mattias-Sehlstedt, thanks for the push-back. I'll explain why I don't think using a separate branch is sufficient here, and why the feature in this PR is useful.

When you use OpenAPI Generator, the API spec is the source of truth. At the same time, schemaMappings / importMappings exist so you can substitute generated models with custom implementations (e.g., enums with extra behavior, or reused domain types to avoid unnecessary remapping).

The problem is: once a schema is substituted, it is no longer generated, and from that moment it can drift from the spec without any direct signal.

A branch-based diff can help as a one-time/manual check, but it is not a stable mechanism for continuous verification in normal CI flows.

forcedGenerateSchemas keeps the ability to generate selected mapped/imported schemas as a reference copy, even if those types are not used at runtime. That enables tests which verify the custom replacement still matches the spec-driven model:

• enum values stay aligned with schema enum values (easy to assert in a unit test when you have both classes available)
• object shape/required fields still match (e.g., reflection-based assertions in unit tests)

Also, this was not introduced as a theoretical capability. The need arose organically from my real-world usage of the kotlin-spring generator at my workplace, where we map selected schemas to custom domain types but still need an automated safety check against spec drift.

I would argue against it being a feature-for-feature's-sake, but rather an automated guardrail for teams that intentionally customize model mappings while still treating the OpenAPI spec as authoritative.

And I think this drift-check capability might actually reduce pressure for additional small generator features. Without a guardrail, every mismatch risk tends to become a request for another targeted option. With this option one can keep custom mapped/imported models and still verify conformance against spec-derived reference models directly in unit tests. So instead of adding many narrowly-scoped features over time, this provides one general mechanism to safely support customization while keeping the OpenAPI spec the real source of truth.

I also think the current suppression behavior with importMappings / schemaMappings is stricter than necessary.

I understand suppressing generation when the mapped/imported target FQN exactly matches what would be generated (to avoid duplicate/conflicting classes). But suppressing the original schema unconditionally for any schemaMappings / importMappings entry removes the useful capability this PR restores, on an optional per-schema basis, without forcing users to generate everything.

[wing328]

thanks for the pr

the use case sounds valid.

let's give it a try