Add security schemes filter normalizer option

[limentas]

This PR adds new normalizer option to remove unnecessary security schemes. I have decided to make it similar to FILTER option to have this functionality more universal and allow to filter schemes by name and by type.
I have tried to follow DRY principle and uniform the logic with current FILTER implementation that's why it required to touch existent logic.
I have also moved FILTER parse logic outside loop to not repeat it every iteration.

TODO:

• add more unit tests for the new logic
• make sure that new logic works well with SET_BEARER_AUTH_FOR_NAME option
• document new option
• consider to remove security object references from operations for removed security schemes
• consider to fix log message marked as internal only (x-internal: true) by the {} filter

Resolves #22954

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

Adds SECURITY_SCHEMES_FILTER to keep selected security schemes by key or type, remove others from components.securitySchemes, and clean all references globally, per operation, webhooks, callbacks (including nested), and components’ path items. Also adds a reusable, backward‑compatible filter framework with single-pass parsing and clearer errors/logging. Resolves #22954.

• New Features

  • SECURITY_SCHEMES_FILTER supports key:/type: (e.g., key:api_key1|api_key2;type:oauth2; types: apiKey|http|mutualTLS|oauth2|openIdConnect). Removes non-matching schemes and their references, drops emptied requirements while keeping original empty ones, and works with SET_BEARER_AUTH_FOR_NAME (conversion happens before filtering). Cleans references across global security, operations, webhooks, callbacks (incl. nested), and components’ callbacks and path items.

• Refactors

  • Introduces BaseFilter; Filter is now the operations filter and remains backward compatible with custom filters; adds SecuritySchemesFilter. New hooks: createOperationsFilter, createSecuritySchemesFilter; parse FILTER/SECURITY_SCHEMES_FILTER once; clearer usage-and-input errors and log messages.

^{Written for commit 5ff2e3d. Summary will update on new commits.}

[limentas]

I found one logging issue and I would like to fix it since I touched this code. The problem is normalizer logs message like
"operation xxx marked as internal only (x-internal: true) by the {} FILTER" from here:
https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java#L2076
But actually it is wrong because if we found a match (and we can find multiple) then we set x-internal to false and then the message would look like:
operation xxx marked as not internal (x-internal: false) by the {} FILTER
I would change the logic and emit a message only when we remove an operation:
operation xxx marked as internal only (x-internal: true) by FILTER parameter. In this case we cannot say which part is exactly doing this because the logic in inverted here. We can just say that the operation didn't match all filter options.
Is this ok?

[wing328]

thanks for the draft.

please put it on hold for the time being

[limentas]

@wing328 any ideas on how to proceed with this feature?

[wing328]

let me try to open a PR later this week...

[limentas]

let me try to open a PR later this week...

I take this as you don't like the proposal in this PR. This is fine. Just let me know if you need any help from my side.

[wing328]

@limentas when you've time, can you please PM me via Slack to further discuss this?

[wing328]

here is the link to join our slack: https://join.slack.com/t/openapi-generator/shared_invite/zt-36ucx4ybl-jYrN6euoYn6zxXNZdldoZA

[wing328]

consider to remove security object references from operations for removed security schemes

can you please elaborate on this one? I thought this should be done as part of the fix as the goal is remove the security definition (that the users do not want for whatever reasons) from the whole spec as if it has never been defined in the security schema section.

[wing328]

consider to fix log message marked as internal only (x-internal: true) by the {} filter

I do not completely this one. Please elaborate.

[wing328]

I think your PR is almost done so let's push it through the finish line

(my approach is too idealistic so I don't think I've time to finish it)

[limentas]

@wing328

can you please elaborate on this one?

At this moment I remove security schemas definitions only from components->securitySchemes. But these schemas are referenced in top-level security declaration and also can be referenced in operations. For example in petstore example there is petstore_auth security schema. Let's say new filter removes it. Then this schema is referenced also in POST /pet method. Should I remove such references as well?

I do not completely this one. Please elaborate.

If I remember correctly the problem is that FILTER logging is incorrect.
There is this method: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java#L2075
The message is logged when a match with one of the filters was found. But in this case actually x-internal: false added. The logic is inversed. Anyway this is just a small finding I would add a fix as a separate PR to make reviewers lives easier.

[limentas]

I have implemented the logic to clean up all references of removed security schemes.
The PR is ready for review.

[cubic-dev-ai]

3 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/customization.md">

<violation number="1" location="docs/customization.md:759">
P2: SECURITY_SCHEMES_FILTER is documented as setting x-internal on operations, but the implementation removes security schemes and cleans their references instead.</violation>
</file>

<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java:694">
P1: Security-scheme cleanup is incomplete: it only strips keys from operation security and does not prune empty requirements or clean `openAPI.security`, which can leave dangling refs and alter auth semantics.</violation>

<violation number="2" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java:2509">
P1: `SECURITY_SCHEMES_FILTER` can throw an NPE when a security scheme has no type because `scheme.getType()` is dereferenced without a null check.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[limentas]

Fixed code review remarks

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java:693">
P2: Security-scheme cleanup skips callback operations, so callback `security` requirements can still reference schemes that were removed from `components.securitySchemes`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[limentas]

Added clean up code for callbacks and webhooks

[cubic-dev-ai]

2 issues found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java">

<violation number="1" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java:354">
P2: Renaming the protected FILTER factory without a compatibility bridge breaks downstream subclass overrides of `createFilter`, silently disabling custom filtering.</violation>

<violation number="2" location="modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java:729">
P2: Security-scheme cleanup does not recurse into callback operations nested under regular operations, so deleted schemes can remain referenced there.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[wing328]

thanks for the PR which has been merged 👍