A specification generated from the router, which is drift-proof until there are two routers describing two versions.
paths:
/v1/orders/{id}:
get:
responses: { '200': { $ref: '#/components/schemas/OrderV1' } }
/v2/orders/{id}:
get:
responses: { '200': { $ref: '#/components/schemas/OrderV2' } }
# and the shared component that both referenced, changed
# for v2 and silently changing v1's documentation.
Generating from the router guarantees that a documented endpoint exists and guarantees nothing about the schema, which was a hand-maintained component shared between versions. Splitting the schemas so each version owns its own is duplication that is genuinely correct — the whole point of a version is that the shapes diverge.