[Examples] Respect numeric schema bounds when generating examples

JA
6d ago
+164-10

Summary

Fixes #25234.

Generated numeric examples can violate the schema: an integer with maximum: -5 currently produces 0, and minimum: 0 with exclusiveMinimum: true also produces 0. The shared example generator now keeps generated values within representable numeric bounds.

Changes

  • Reuse the existing bound resolvers for OpenAPI 3.0 boolean and OpenAPI 3.1 numeric exclusive bounds.
  • Round bounds appropriately for integers and serialized float/double values, and handle negative maximum-only ranges.
  • Add regression coverage for numeric formats, fractional/exclusive bounds, narrow intervals, and integer precision.
  • Document the behavior in the customization guide.

Test

  • Reproduced both invalid examples with the original implementation.
  • A full ./mvnw clean package run passed before the final integer-saturation edge-case adjustment; the final source was rebuilt and retested with the CLI and core-module commands below.
  • ./mvnw -pl modules/openapi-generator-cli -am package -Dtest=ExampleGeneratorTest -Dsurefire.failIfNoSpecifiedTests=false: 174 tests passed.
  • ./mvnw -pl modules/openapi-generator -am test: 5,645 tests, no failures/errors, 14 skipped by the existing suite.
  • ./bin/generate-samples.sh: all 829 configurations succeeded, with no sample changes.
  • ./bin/utils/export_docs_generators.sh: completed, with no generated documentation changes.
  • Generated HTML documentation and Spring server stubs from the issue's schema. The examples changed from {"celsius": 0, "level": 0} to {"celsius": -5, "level": 1}.

Before and after

The screenshot below shows actual HTML documentation generated from the same schema, using the original implementation on the left and this change on the right.

numeric-example-bounds

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
    Commit all changed files. No sample directories were deleted.
  • Language-specific technical committee mention: not applicable; this change is in shared example generation.

Summary by cubic

Fixes generated numeric examples so they respect minimum, maximum, exclusiveMinimum, and exclusiveMaximum bounds from the schema.

  • Reuses existing bound resolvers for OpenAPI 3.0 boolean and OpenAPI 3.1 numeric exclusive bounds.
  • Rounds integer and float/double values to representable bounds, and handles negative maximum-only ranges.
  • Adds regression tests covering numeric formats, fractional and exclusive bounds, narrow intervals, and integer precision.
  • Documents the behavior in the customization guide.