My company updates our APIs in such a way that backwards-compatible changes propagate backwards to all API versions, whereas breaking changes do not.
We are having a difficult time modeling this in OpenAPI tooling, however. We can have common reference objects that we could share across multiple API version files, but we don’t have an easy way to make some of these edits (like adding new fields) propagate to all API versions, while having other edits (like removing fields, renaming fields) not propagate. In most cases, field descriptions can be shared, but in some cases, we’d like them to be different.
Right now, we “solve” this problem by maintaining four different YAML API definition files, one for each of our API versions. However, having to edit each individual file whenever we want to add a field, fix a typo, or clarify a description is a huge drag, and the problem will only get worse as we continue to release more API versions.
How do other folks deal with this situation? We could, of course, change our API support model or backwards-propagation of changes, but that seems like a very “tail wagging the dog” system that sacrifices end user value just to make our lives easier from a maintenance perspective.
Currently, we are looking at some kind of pre-processor/compilation step for our API to address this issue, but we’re wondering if there is existing tooling out there that solves the problem, as we must not be the only ones experiencing this.