Rolling back an OpenAPI schema change without breaking already-generated clients
0 reputation · 18 Apr 2021, 12:26 UTC
Assume a REST API documented with OpenAPI 3.0.x, where consumers generate their own clients from the published document. A recent schema change added a new enum value to a response field and made one previously optional request field required. The deployment now needs to be rolled back, but some consumers may have already regenerated clients against the newer document.
The uncertainty is whether reverting the document is actually safe in both directions. Clients generated from the new document may reject old responses if a strict deserializer fails on unknown enum values, and clients still on the old document will fail validation against the tightened required field if the server behavior is also reverted inconsistently. Generated client behavior here varies by generator and language, and Swagger UI rendering does not prove what a validator or deserializer will accept.
Which of these two edits should be treated as breaking for rollback purposes, given that enum strictness differs across generators? Does a safe rollback require keeping both document versions addressable during a deprecation window, or is diffing and classifying each change (additive, tightening, removing) sufficient? What verification would confirm compatibility before reverting: regenerating representative clients from both documents, or contract tests with recorded consumer payloads?