search

OpenAPITools / openapi-diff

Utility for comparing two OpenAPI specifications.
Apache License 2.0
787 stars 152 forks source link

Do not fail with breaking changes when major version is bumped #460

Open jdnvn opened 1 year ago

jdnvn commented 1 year ago

Hello!

I was wondering if it makes sense to pass the diff check if there are breaking changes, but the major version has been bumped. Right now, I am planning to use this as a required workflow on GitHub PRs and I want to give developers the opportunity to get around the check if they bump the version.

Would love this as a potential built in feature or option when running.

Thanks

joschi commented 1 year ago

@jdnvn Thanks for this suggestion!

I like the idea, but one issue I see is that info.version is a string with no inherent semantics:

version string REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API implementation version).

https://swagger.io/specification/#info-object

This means that even if OpenAPI Diff knew what semantic versioning is, there's no guarantee that the info.version field actually does contain one.

For all practical purposes, the following values are valid "versions": one, two, foobar1.

Any suggestions how this change should work in these cases? Maybe an explicit flag which assumes info.version is a semver string and fail otherwise?

igokoro commented 1 year ago

Is version change something that can be implemented as SPI extension? There's very little documentation for ExtensionDiff, so it's hard to tell if it's got enough information/power to override the diff produced by the tool.