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 filter components.securitySchemes by key or type and remove non-matching entries, reducing unused auth configs. Also refactors operation filtering for better performance and extensibility. Resolves #22954.

• New Features

  • SECURITY_SCHEMES_FILTER accepts key: and/or type: (e.g., key:api_key1|api_key2;type:oauth2); non-matching schemes are removed from components.securitySchemes.
  • Compatible with SET_BEARER_AUTH_FOR_NAME: conversion to HTTP bearer happens before filtering.
  • Added docs with examples in docs/customization.md.

• Refactors

  • Replaces legacy Filter with OperationsFilter and introduces shared BaseFilter used by both operations and security-schemes filters.
  • Parses FILTER once per normalization and improves error messages with clear usage and input.

^{Written for commit 19dae24. 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.