Skip to content

Make the OpenAPINormalizer extensible #20995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 4 commits into from
Apr 11, 2025
Merged

Make the OpenAPINormalizer extensible #20995

merged 4 commits into from
Apr 11, 2025

Conversation

jpfinne
Copy link
Contributor

@jpfinne jpfinne commented Mar 30, 2025

fix #20994

Allow configuration of the OpenAPINormalizer
New normalizer rule: NORMALIZER_CLASS to provide the class name of the extended OpenAPINormalizer.

Change the private modifiers to protected to allow overriding and extensions of behaviour.

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 Git BASH)
    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 is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@jpfinne
Make the OpenAPINormalizer configurable
d888ea4 
Add comment to force rebuild
@Mattias-Sehlstedt Mattias-Sehlstedt mentioned this pull request Apr 6, 2025
Open
5 tasks
wing328
wing328 reviewed Apr 7, 2025
View reviewed changes
modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java Outdated
* @param visitedSchemas a set of visited schemas
* @return Schema
*/
protected Schema doNormalizeSchema(Schema schema, Set<Schema> visitedSchemas) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for the PR

which looks good overall

but what's the reason behind to further breaking down normalizeSchema with 1 additional function doNormalizeSchema?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but what's the reason behind to further breaking down normalizeSchema with 1 additional function doNormalizeSchema?

public Schema normalizeSchema(Schema schema, Set<Schema> visitedSchemas) {
has 2 purposes:

  1. check if not already processed
  2. perform the actual normalization

I want to be able to override the 2.

Another option is to keep the original normalizeSchema and be sure that all options can be overriden.
For example, there is a need to uncomment the handling of normalizeAdditionalProperties

     if (schema.getAdditionalProperties() != null) {
           normalizeAdditionalProperties(m, visitedSchemas);
     }

or split the normalization of composed schema:

} else if (ModelUtils.isComposedSchema(schema)) { // composed schema
   return normalizeComposedSchema(schema, schemaVisited);
}

and copy the content of the inner block to the new protected Schema normalizeComposedSchema() method

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok. thanks for the explanation

i may rename the function 'doNormalizeSchema' with a better name later

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

quick question

why not just override normalizeSchema and copy 1 (check if not already processed) in the overidden function?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not just override normalizeSchema and copy 1 (check if not already processed) in the overidden function?

The new implementation does exactly that.
Thanks for the suggestion.

@wing328 wing328 added Enhancement: General OpenAPI Normalizer Normalize the spec for easier processing labels Apr 7, 2025
@wing328 wing328 added this to the 7.13.0 milestone Apr 7, 2025
wing328
wing328 reviewed Apr 9, 2025
View reviewed changes
modules/openapi-generator/src/main/java/org/openapitools/codegen/OpenAPINormalizer.java
return new OpenAPINormalizer(openAPI, inputRules);
}
}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one more thing. can you please update the doc with more info on NORMALIZER_CLASS? there's no doc at the moment for this new rule

https://github.com/openapitools/openapi-generator/blob/master/docs/customization.md#openapi-normalizer

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

@wing328 wing328 merged commit 4fc46cb into OpenAPITools:master Apr 11, 2025
14 checks passed
@wing328
Copy link
Member

wing328 commented Apr 11, 2025

thanks for the PR. let's give it a try

have a nice weekend

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@wing328 wing328 wing328 left review comments

Assignees
No one assigned
Labels
Enhancement: General OpenAPI Normalizer Normalize the spec for easier processing
Projects
None yet
Milestone
7.13.0
Development

Successfully merging this pull request may close these issues.

[REQ] Make OpenApiNormalizer extensible
2 participants
@jpfinne @wing328