docs: clarify that supportingFiles is an allow-list (#22238)

[brbousnguar]

Closes #22238.

What is actually going on

#22238 reports that the restclient library generates an ApiClient which
references ServerConfiguration / ServerVariable without those classes being
available, and suggests adding imports. Two things about that:

• They are in the same package as ApiClient (invokerPackage), so an
  import would not help — and would not compile.
• They are already registered as supporting files, and have been since
  [java] Support templated servers #4998: JavaClientCodegen.java:572-573 adds ServerConfiguration.mustache
  and ServerVariable.mustache, and :764 adds ExceptionProvider.mustache
  for restclient. A default run emits all of them next to ApiClient.java.

The reporter's build fails because of their own Maven configuration:

<supportingFilesToGenerate>ApiClient.java,Authentication.java,HttpBasicAuth.java,HttpBearerAuth.java,ApiKeyAuth.java,JavaTimeFormatter.java,RFC3339DateFormat.java</supportingFilesToGenerate>

That maps to the supportingFiles global property, which DefaultGenerator
treats as a fixed allow-list:

shouldGenerate = supportingFilesToGenerate.contains(support.getDestinationFilename());

The list was written before #21699 taught the restclient ApiClient about
servers, so ServerConfiguration.java, ServerVariable.java and
ExceptionProvider.java are now skipped while the emitted ApiClient still
references them. Reproduced with the CLI equivalent on a minimal spec: with
--global-property supportingFiles="ApiClient.java:..." exactly those three
files are missing from the output; without it, they are all generated and also
listed in .openapi-generator/FILES. @BobLuursema reached the same conclusion
in the issue thread.

So there is no generation bug to fix — but the trap is undocumented in the
places a user actually reads, and the Maven plugin's own Javadoc for the
option describes the wrong thing. This PR fixes that.

Changes

• docs/customization.md — new paragraph in Selective generation noting that
  an explicit list replaces the full set rather than adding to it, that
  supporting files reference one another (with the restclient ApiClient
  example), that each skip is logged at INFO level, and that
  .openapi-generator-ignore is the upgrade-safe alternative.
• docs/global-properties.md — one-line cross-reference to that caveat, since
  this is where supportingFiles is documented as a global property and where a
  user building the list reads first.
• CodeGenMojo.java — the Javadoc on supportingFilesToGenerate read "A comma
  separated list of models to generate. All models is the default.", copy-pasted
  from modelsToGenerate. Corrected, with the same caveat.
• modules/openapi-generator-maven-plugin/README.md — caveat added to the
  supportingFilesToGenerate row.
• JavaClientCodegenTest — two tests:
  • testRestClientSupportingFilesAllowListSkipsApiClientCompanions_issue_22238
    reproduces the reported configuration: with the supportingFiles global
    property set to ApiClient.java, ApiClient.java is still emitted while the
    ServerConfiguration, ServerVariable and ExceptionProvider it references
    are skipped. This pins and documents the footgun itself.
  • testRestClientDefaultGenerationIncludesCompanionFiles pins the premise the
    issue assumed had regressed — a default restclient run emits all four files
    side by side — so the registration cannot silently disappear.

No generator behaviour changes, so samples/ is untouched.

Testing

./mvnw -pl modules/openapi-generator -Dtest='JavaClientCodegenTest#testRestClientDefaultGenerationIncludesCompanionFiles+testRestClientSupportingFilesAllowListSkipsApiClientCompanions_issue_22238' clean test
./mvnw -pl modules/openapi-generator,modules/openapi-generator-maven-plugin clean test
./mvnw -pl modules/openapi-generator,modules/openapi-generator-maven-plugin checkstyle:check -Dcheckstyle.includeTestSourceDirectory=true

All green: the core library reports Tests run: 5270, Failures: 0, Errors: 0, Skipped: 14 with JavaClientCodegenTest at 299/0, the Maven plugin module
reports 27/0, and checkstyle passes with test sources included.

I also checked the default-generation test is meaningful: commenting out the
ServerConfiguration.mustache registration in JavaClientCodegen makes it fail
with File does not exist when it should: .../ServerConfiguration.java.

One note for anyone reproducing locally, since it cost me a round: the clean is
load-bearing. This repo enables the Develocity Maven extension with the local
build cache on, and a cached target/classes from before #24783 still contained
the ~30 mustache templates that commit moved from cpp-boost-beast-client/ to
cpp-boost-beast-common/. Maven's resources plugin never deletes removed files,
so the template locator resolved the stale copies and three unrelated tests
failed (cppboostbeast.ModelApiSurfaceTest and both
templating.GeneratorTemplateContentLocatorAdditionalDirsTest methods). They
pass on a clean build. Relatedly, mvn ... test compile cannot be used here at
all: the second lifecycle pass recompiles the antlr4-generated
KotlinLexer/KotlinParser against the compile classpath, where
antlr4-runtime is test-scoped, and it fails before the reactor reaches the
Maven plugin module.

PR checklist

• Read the contribution guidelines.
• Ran the build; samples and generator docs are unchanged by this PR
  (documentation and tests only), so there is nothing to regenerate.
• @Nicklas2751 (Java Spring 6 RestClient) — tagging you since the example in
  the docs is the restclient ApiClient you maintain; happy to reword.

---

Summary by cubic

Clarifies that the supportingFiles option is a fixed allow-list, not an addition, and fixes the docs and Maven plugin Javadoc that described it incorrectly.

Issue #22238 reported that the restclient ApiClient references ServerConfiguration, ServerVariable, and ExceptionProvider without generating them. A default run does generate them; the reporter's build failed because their explicit list predates those references, and the allow-list skips anything not listed. This PR documents that trap instead of changing generation.

• Adds a paragraph to the selective generation docs, a cross-reference in docs/global-properties.md, and a recommendation to use .openapi-generator-ignore as the upgrade-safe alternative.
• Corrects the CodeGenMojo Javadoc for supportingFilesToGenerate (previously copy-pasted from modelsToGenerate) and the corresponding Maven plugin README row.
• Adds two tests: one reproducing the reported configuration to pin the allow-list behavior, and one verifying a default restclient run emits all referenced files.

No generator behavior changes; samples/ is untouched.

^{Written for commit 72b9504. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/global-properties.md">

<violation number="1" location="docs/global-properties.md:26">
P3: The added sentence is hard to parse: "files a newer version of a generator added are not generated" is missing a relative pronoun. Since this PR's purpose is doc clarity, rephrase, e.g. "files added by a newer version of a generator are not generated unless the list mentions them".</violation>

<violation number="2" location="docs/global-properties.md:26">
P2: This applies the supporting-file upgrade warning to `models` and `apis`, whose lists filter model/API names rather than supporting-file outputs. Separate those name filters from the warning that newer supporting files are omitted only when `supportingFiles` is restricted.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: This applies the supporting-file upgrade warning to models and apis, whose lists filter model/API names rather than supporting-file outputs. Separate those name filters from the warning that newer supporting files are omitted only when supportingFiles is restricted.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/global-properties.md, line 26:

<comment>This applies the supporting-file upgrade warning to `models` and `apis`, whose lists filter model/API names rather than supporting-file outputs. Separate those name filters from the warning that newer supporting files are omitted only when `supportingFiles` is restricted.</comment>

<file context>
@@ -23,6 +23,8 @@ title: Global Properties
 | modelTests                                        | Allows the user to define if model tests will be generated. Prefer using the more robust `.openapi-generator-ignore`.         | `true` or `false`                                    |
 | splitOperationsByContentType                      | Generates one operation per request/response content-type when an operation exposes several with different schemas            | `true` or `false`                                    |
 
+Note that `supportingFiles`, `models` and `apis` take an allow-list: files a newer version of a generator added are not generated unless the list mentions them, which can break the generated code — see [Selective generation](./customization.md#selective-generation).
+
 
</file context>

Suggested change

	Note that `supportingFiles`, `models` and `apis` take an allow-list: files a newer version of a generator added are not generated unless the list mentions them, which can break the generated code — see [Selective generation](./customization.md#selective-generation).
	Note that `supportingFiles` is an allow-list: supporting files added by a newer generator version are not generated unless the list mentions them, which can break the generated code. `models` and `apis` also accept allow-lists of model and API names, respectively — see [Selective generation](./customization.md#selective-generation).

[cubic-dev-ai]

P3: The added sentence is hard to parse: "files a newer version of a generator added are not generated" is missing a relative pronoun. Since this PR's purpose is doc clarity, rephrase, e.g. "files added by a newer version of a generator are not generated unless the list mentions them".

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/global-properties.md, line 26:

<comment>The added sentence is hard to parse: "files a newer version of a generator added are not generated" is missing a relative pronoun. Since this PR's purpose is doc clarity, rephrase, e.g. "files added by a newer version of a generator are not generated unless the list mentions them".</comment>

<file context>
@@ -23,6 +23,8 @@ title: Global Properties
 | modelTests                                        | Allows the user to define if model tests will be generated. Prefer using the more robust `.openapi-generator-ignore`.         | `true` or `false`                                    |
 | splitOperationsByContentType                      | Generates one operation per request/response content-type when an operation exposes several with different schemas            | `true` or `false`                                    |
 
+Note that `supportingFiles`, `models` and `apis` take an allow-list: files a newer version of a generator added are not generated unless the list mentions them, which can break the generated code — see [Selective generation](./customization.md#selective-generation).
+
 
</file context>

Suggested change

	Note that `supportingFiles`, `models` and `apis` take an allow-list: files a newer version of a generator added are not generated unless the list mentions them, which can break the generated code — see [Selective generation](./customization.md#selective-generation).
	Note that `supportingFiles`, `models` and `apis` take an allow-list: files added by a newer version of a generator are not generated unless the list mentions them, which can break the generated code — see [Selective generation](./customization.md#selective-generation).