Build a validated Spring create endpoint with ProblemDetail errors

{ "productId": null, "quantity": 0 }

{
  "type": "https://aporeon.com/problems/validation",
  "title": "Request validation failed",
  "status": 400,
  "errors": { "productId": "must not be null", "quantity": "must be greater than or equal to 1" }
}

• Use a request DTO with Jakarta validation annotations.
• Keep controller logic limited to HTTP concerns and service delegation.
• Return a location URI for the created resource.
• Use a deterministic field-error map when multiple constraints fail.
• Do not serialize the JPA entity as the API contract.

1. Define input and output records owned by the API boundary.
2. Add @Valid to the request body and validation annotations to fields.
3. Delegate creation to an application service and return ResponseEntity.created.
4. Handle MethodArgumentNotValidException in @RestControllerAdvice.
5. Build a stable ProblemDetail and attach a field-to-message map.

record CreateOrderRequest(
    @jakarta.validation.constraints.NotNull java.util.UUID productId,
    @jakarta.validation.constraints.Min(1)
    @jakarta.validation.constraints.Max(100) int quantity) {}

record OrderResponse(java.util.UUID id, java.util.UUID productId, int quantity) {}

@org.springframework.web.bind.annotation.RestController
class OrderController {
    private final OrderService service;
    OrderController(OrderService service) { this.service = service; }

    @org.springframework.web.bind.annotation.PostMapping("/orders")
    org.springframework.http.ResponseEntity<OrderResponse> create(
            @jakarta.validation.Valid
            @org.springframework.web.bind.annotation.RequestBody CreateOrderRequest request) {
        var created = service.create(request);
        var location = java.net.URI.create("/orders/" + created.id());
        return org.springframework.http.ResponseEntity.created(location).body(created);
    }
}

@org.springframework.web.bind.annotation.RestControllerAdvice
class ApiErrors {
    @org.springframework.web.bind.annotation.ExceptionHandler(
        org.springframework.web.bind.MethodArgumentNotValidException.class)
    org.springframework.http.ProblemDetail validation(
            org.springframework.web.bind.MethodArgumentNotValidException ex) {
        var errors = new java.util.TreeMap<String, String>();
        ex.getBindingResult().getFieldErrors().forEach(error ->
            errors.putIfAbsent(error.getField(), error.getDefaultMessage()));

        var problem = org.springframework.http.ProblemDetail.forStatus(400);
        problem.setType(java.net.URI.create("https://aporeon.com/problems/validation"));
        problem.setTitle("Request validation failed");
        problem.setProperty("errors", errors);
        return problem;
    }
}

Validation is O(f) in the number of constrained fields. Error collection is O(e log e) here because TreeMap provides deterministic key ordering; for this small boundary the cost is negligible.

• Malformed JSON fails before Bean Validation and needs its own generic 400 handler.
• Primitive int distinguishes an omitted quantity only through its default zero; use Integer if omission must differ from zero.
• Several annotations may fail for one field, so the contract deliberately chooses the first message.
• Domain conflicts such as a missing product are not field-validation failures.

• Submit quantity 0, 1, 100, and 101.
• Submit a null product ID and assert the stable problem type, title, status, and errors property.
• Assert the service is not invoked for invalid requests.
• Assert a valid response includes 201, body, and the exact location header.

• Without @Valid, annotations exist but request validation never runs.
• Returning ex.getMessage() leaks framework detail and creates an unstable client contract.
• Putting creation logic in the controller obscures transaction and authorization boundaries.
• Returning the entity couples lazy associations and persistence fields to the API.