feat(core): expose request body named examples to templates

[Mattias-Sehlstedt]

Adds so that any examples defined in a request body are properly attached to a CodegenParameter's examples so that they can be accessed within the mustache templates. This logic already exists for when reading a swagger-core OAS Parameter object, but have now also been extended to request bodies.

Fixes #23607

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

Expose all named request body examples to mustache via CodegenParameter.examples. Previously only a single example value was available; now the examples map from the request body’s first media type is attached while CodegenParameter.example remains unchanged.

• fromRequestBody now sets examples from the first content media type when present.
• Add getFirstContentMediaType and hasMediaType helpers; refactor getContentType, addConsumesInfo, getConsumesInfo, and addProducesInfo to use them (null-safety, no behavior change).
• Add tests and a spec path (/example6/multiple_examples) verifying multiple request body examples are accessible.
• No template migrations required; templates can iterate over request body examples.

^{Written for commit 321ce8d. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[jpfinne]

@Mattias-Sehlstedt thanks for the PR. I've used our code successfully in a custom generator.
Just a pity that only the first media type is kept.

Could you add the equivalent to CodegenResponse? Currently we have List<Map<String, Object>> examples.
And the map contains for example Map.of("exampleName", null, exampleValue", "{\\"name\\": \\"John\\" }) . The exampleValue is the result of json.toString() -> extra double quotes.

We loose the summary and the description of the swagger io.swagger.v3.oas.models.examples.Example
The map could contain a new entry with the swagger `Example' . That keeps backward compatibility and allow new templates to use the full Example.

For better customization, the 2 new ExampleGenerator(schemas, this.openAPI); in DefaultCodeGen could be replaced by a call to
protected getExampleGenerator(Map<String, Schema>).
ExampleGenerator has too many private method. Make them protected so we can easily extend it.
What do you think?

Currently I do something like this:

    @Override
    public CodegenResponse fromResponse(String responseCode, ApiResponse response) {
        CodegenResponse cr = super.fromResponse(responseCode, response);
        if (response.getContent() != null) {
            response.getContent().forEach((s, mediaType) -> {
                Map<String, Example> examples = mediaType.getExamples();
                if (examples != null) {
                    cr.vendorExtensions.put("x-responseExamples", examples);
                }
            });
        }
        return cr;
    }

[Mattias-Sehlstedt]

I think they both make sense, and that example generation and management in general could be harmonized and clarified so that it would be easier to handle them. But I am not sure that I would want to introduce those changes in this PR, since this is manly target against the exact issue reported.

I could create a new issue based upon your suggestions and look into refactoring examples management in general.

When you suggest better extension of the ExampleGenerator, do you mean as in the context of having a customer generator? I though that that was basically dead tech and that most extensibility was managed by configuration settings instead (and that inheritance is generally just for allowing a different language generator to do slight modifications).

[jpfinne]

@Mattias-Sehlstedt a configurable class name of the ExampleGenerator can also be used. Similar to the extensible OpenapiNormalizer

[jpfinne]

The more I look at the example structures, the less I like it.

class	example	examples
CodegenResponse		List<Map<String, Object>> examples
CodegenMediaType	Object example	Map<String, Example> examples
CodegenParameter	String example	Map<String, Example> examples
CodegenProperty	String example
CodegenOperation		List<Map<String, String>> examples List<Map<String, String>> requestBodyExamples

How can we make it more consistent? To avoid breaking changes, we could have a new CodeGenSample and deprecate the existing example fields