Replies: 2 comments 1 reply
-
Hi @rjaus, I recently added a solution for this use case based on a issue in oasdiff and I am looking for feedback. Related to your specific use-case, we could extend my solution by adding an Ideally, I think this should be integrated into OpenAPI spec to support graceful deprecations. Any feedback is welcome! |
Beta Was this translation helpful? Give feedback.
-
@rjaus this seems to be tracked by issue #782. It might also be relevant in Moonwalk (OAS 4), so I'm going to transfer the discussion over there and leave #782 here for potential 3.x work. |
Beta Was this translation helpful? Give feedback.
-
Hi,
Big fan of OpenAPI Spec. At Xero we've moved to generating all our SDKs from an OpenAPI spec, and for the most part it's been incredibly successful!
One issue that has come up a few times is method renaming & deprecation
In a scenario that a method was incorrectly named during the initial release, or perhaps the endpoint has been renamed (less likely). This results in the OAS spec requiring updating, which results in the method name changing in all of our SDKs, which results in a breaking change.
If we were manually building SDK's, I'd create this method as an alias, as to avoid an immediate breaking change. Add in the release notes that the old method name will be deprecated in the next major version, add some warnings to on install (ruby / node) and then continue on.
In the next major release I'd remove the alias / old method & note the breaking change.
I presently have two of these changes blocked from release as they will be immediate breaking changes, && they will break across our SDK's. An example: XeroAPI/xero-ruby#200
From researching this issue last time it came up, I couldn't find a solution in the OAS. Keen to hear how others have resolved this? Or discuss how OAS could support this use case.
Thanks!
Beta Was this translation helpful? Give feedback.
All reactions