Tavis.OpenApi icon indicating copy to clipboard operation
Tavis.OpenApi copied to clipboard

Implement semantic diffing capability

Open darrelmiller opened this issue 8 years ago • 2 comments

It would be useful to be able to take two OpenAPIDocument models and create a list of differences. Ideally the diff should describe the type of difference and where applicable hold a reference to the old and new value. We should also know the context of where in the document the difference occurred.

darrelmiller avatar Jun 18 '17 12:06 darrelmiller

It would be useful to be able to determine whether a change should trigger a major, minor or patch version number change according to semver. A 'semantic OpenAPI version' spec/guidance would allow tools to be consistent in this regard.

MikeRalphson avatar Jun 18 '17 15:06 MikeRalphson

As we are not requiring users of OpenAPI definitions to use semantic versioning I don't think OpenAPI should get into the business of defining what is and isn't a breaking change.

However, I do think we should have a way for a user to define what types of changes they want consumers to opt-into, versus the types of changes that will just get pushed. If a user defines these policies, then we could review the diffs based on those policies and provide guidance on how an API should be versioned.

darrelmiller avatar Jun 19 '17 13:06 darrelmiller