docs: improve validation section for service module. - #2625
Conversation
There was a problem hiding this comment.
Pull request overview
Updates the Timefold Solver Service REST API documentation to remove a TODO and expand guidance on request validation and OpenAPI generation.
Changes:
- Adds guidance encouraging structural validation via OpenAPI annotations.
- Replaces a TODO with a more detailed explanation of influencing the generated OpenAPI spec via
@Schemaand Bean Validation annotations.
Suppressed comments (1)
docs/src/modules/ROOT/pages/running-timefold-solver/service/rest-api.adoc:547
- The statement that
@Schemaconstraints are enforced at runtime needs to be qualified because the request schema validation is profile/feature gated (dev/test only, and can be disabled), otherwise readers may assume it applies in production.
The `@Schema` annotation lets you document a field (`description`), and its attributes such as `required`, `pattern`, `minimum` and `maximum` are also enforced at runtime: an incoming request that violates them is rejected with a `400` response before it reaches your model.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| By default, validation on the input is based on the xref:./rest-api.adoc#openAPISpecification[OpenAPI Specification annotations]. | ||
| Most of the structural validations (e.g. required fields, minimum number of items in collections, etc.) should be implemented using those annotations. |
There was a problem hiding this comment.
Ad Copilot comment: fair remark, but unless we explain how and when we perform the JSON schema validation in the platform and locally, it just raises more questions.
There was a problem hiding this comment.
Should we create a separate profile then? Because having this validation disabled by default in the JAR is sort of weird.
There was a problem hiding this comment.
We can enable JSON validation locally regardless of the Quarkus profiles and have there a property to opt-out. The platform would need to set the property, because JSON validation is done by the gateway before the model pod starts.
| Alternatively, you can express the same constraints using https://jakarta.ee/specifications/bean-validation/[Jakarta Bean Validation] annotations (such as `@NotNull`, `@Size` or `@Min`/`@Max`) instead of, or in combination with, `@Schema`. | ||
| Quarkus picks these up as well: they are reflected in the generated OpenAPI specification and enforced in the same way. |
There was a problem hiding this comment.
True, but do we want to mention it? For people who are not familiar with OpenAPI and Bean Validation, it's another choice to make.
People who already know Quarkus and these standards don't need us to tell them.
| By default, validation on the input is based on the xref:./rest-api.adoc#openAPISpecification[OpenAPI Specification annotations]. | ||
| Most of the structural validations (e.g. required fields, minimum number of items in collections, etc.) should be implemented using those annotations. |
There was a problem hiding this comment.
Ad Copilot comment: fair remark, but unless we explain how and when we perform the JSON schema validation in the platform and locally, it just raises more questions.
Removed TODO in the validation section and improved the general explainer of the docs.