refactor(enum-utils): add utility methods for simplified enum schema creation

[Mattias-Sehlstedt]

Enum handling has over the years evolved with how they are constructed and interpreted. From just being a String value all the time, to adding better support for numbers, and later that they can be decorated better with both description and deprecated. They also support "defaults" for the cases where one might want to use an enum to express a limited value space, but to also capture that it might not be entirely static (i.e., it might happen that it is extended/shrunk, which is a breaking change).

It is now so complex that I would argue that they are also a suitable candidate for its own Utils class. This is inspired by my comment on a recent upgrade to the enum handling.

If this is considered helpful, then I can also investigate moving further enum logic that resides within the now quite large OpenAPINormalizer to the util class. Once all functionality has been moved, then it would be suitable to investigate creating a CodegenEnum class (as mentioned in the PR thread too) that more formally express and carry the different enum settings that the project supports (similar to what exists for the Discriminator now for example).

This is a minor breaking change to the OpenAPINormalizer since its method createSimplifiedEnumSchema

-protected Schema createSimplifiedEnumSchema(Schema originalSchema, Map<Object, String> enumValues, Map<Object, Boolean> deprecatedValues, String schemaType, String composedType) 
+protected Schema createSimplifiedEnumSchema(Schema originalSchema, Map<Object, EnumUtils.EnumExtensions> enumExtensions, String schemaType, String composedType)

will change slightly with Map<Object, String> enumValues becoming Map<Object, EnumUtils.EnumExtensions> enumExtensions.

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.

---

Summary by cubic

Introduces EnumUtils to centralize enum schema creation and refactors OpenAPINormalizer to use it. Adds CodegenConstants.X_ENUM_DEPRECATED; behavior stays the same.

• Refactors

  • Added EnumUtils.createSimplifiedEnumSchema(...) and EnumExtensions to handle descriptions and deprecations.
  • OpenAPINormalizer#createSimplifiedEnumSchema now delegates to EnumUtils.
  • Added CodegenConstants.X_ENUM_DEPRECATED for the x-enum-deprecated extension.

• Migration

  • Protected method signature change in OpenAPINormalizer:
    • From: createSimplifiedEnumSchema(Schema, Map<Object, String>, Map<Object, Boolean>, String, String)
    • To: createSimplifiedEnumSchema(Schema, Map<Object, EnumUtils.EnumExtensions>, String, String)
  • If you override or call this method, replace the two maps with a single Map<Object, EnumUtils.EnumExtensions> and build entries with new EnumUtils.EnumExtensions(description, deprecated).

^{Written for commit 0e52d13. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[wing328]

This is a minor breaking change to the OpenAPINormalizer since its method createSimplifiedEnumSchema

it's ok as this change should have not impacted to the output (e.g. auto-generated SDKs, etc)