OpenAPITools / openapi-diff

Utility for comparing two OpenAPI specifications.
Apache License 2.0
780 stars 153 forks source link

Make incompatibility checks configurable #551

Closed westse closed 6 months ago

westse commented 11 months ago

The ability to selectively enable or disable an incompatibility check is greatly needed because some checks are not appropriate for a given user's use case, and sometimes they are just incorrect (i.e., due to a bug that has not been fixed yet). A scan of this project's issues shows that configurability is a common request, so it is likely that adoption of and satisfaction with this project will be improved if this is addressed.

Additional benefits that may be realized:

  1. New disabled-by-default incompatibility checks may be added with confidence that no existing users will be broken. This safety net will encourage much more innovation than would otherwise occur.
  2. When openapi-diff itself needs a breaking change then users can easily and safely upgrade assuming previous behavior is still available via a config property.
  3. Any implementation will likely include a central enumeration of all incompatibility checks that can be enabled/disabled via configuration. This serves as a form of documentation which will increase user comprehension.
  4. The ability to set configurable properties can be used for other purposes beyond enabling/disabling incompatibility checks, without any extra code "plumbing". In contrast, adding a CLI or Maven option currently requires much more code, which does not encourage contribution.
sokovnich commented 11 months ago

This is a must-have feature to get changelog between two major API versions (e.g. between /api/v1 and /api/v2). Very useful.

westse commented 7 months ago

Can this be merged? Or at least some feedback? Thanks. CC @joschi