An OpenAPI document generated from the router

A hand-written specification that had been correct in March and described four endpoints that no longer existed.

// the routes are the source: the generator walks them and
// reads the request and response types
#[Route('/api/orders/{id}', methods: ['GET'])]
#[Response(200, OrderResource::class)]
#[Response(404, ProblemDetails::class)]
public function show(OrderId $id): OrderResource { /* ... */ }

// CI: regenerate, and fail on a diff against the committed file

Generating from the router makes drift impossible in one direction — an endpoint that exists is described. It does not make the description good: the generated summaries are the method names, and a specification that is technically accurate and unreadable is a different failure. The fix was that generation covers structure and prose stays hand-written in annotations, which is a boundary that has held.