11 minutes / published

DTOs, ProblemDetail, and the Boring Discipline of a Merge-Ready API

Controller boundaries, RFC 9457 error payloads, pagination metadata, springdoc, and ADR-002.

Entities Do Not Cross The Controller Boundary

The moment entities appear in controller signatures, persistence decisions become public API decisions.

Phase 4 uses DTOs and an ArchUnit rule so the boundary is enforced by CI, not reviewer memory.

ProblemDetail Is A Contract

RFC 9457 gives the API a boring, predictable error shape. Validation and not-found paths return typed ProblemDetail responses that clients can inspect.

The tests go through HTTP because the boundary matters more than the Java object.

Mapper Choice Gets An ADR

Manual mapping is the right course choice for now because learners can read every boundary decision.

ADR-002 leaves a clear future path to MapStruct if duplication becomes the real problem.

Docs Render The Contract

springdoc is pinned exactly and the Swagger proof artifact is linked from README.

Generated docs are not a replacement for tests, but they are part of a merge-ready API surface.