[Java][Spring] Add examples parameter in @Schema annotation for OAS 3.1 spec

PE
10d ago
+161-27

Added handling of examples keyword for OAS 3.1 spec.
They are generated in the corresponding @Schema annotation, next to the singular example

Resolve #24755

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.

Java | @bbdouglas @sreeshas @jfiala @lukoyanov @cbornet @jeff9finger @karismann @Zomzog @lwlee2608 @martin-mfg @KannaKim

Java Spring | @cachescrubber @welshm @MelleD @atextor @manedev79 @javisst @borsch @banlevente


Summary by cubic

Adds support for the OAS 3.1 examples keyword so Java Spring generators emit it in the @Schema annotation alongside the singular example.

  • Adds an examples property to CodegenProperty, populated from the schema's examples list via new toExampleValues / getExampleValueToString hooks that stringify scalar, array, and object values.
  • Refactors AbstractJavaCodegen.toExampleValue so example and examples share the same string escaping and Date handling; error reporting is consolidated in handleExampleException.
  • Updates the Java Spring pojo.mustache template to render examples = { ... } only when at least one value is present.
  • Adds tests and a sample spec (issue_24755.yaml) covering string, integer, array, object, and empty examples lists.
  • Regenerated samples now include the new examples field in CodegenProperty.toString() output.

Resolves #24755.