search

redskap / swagger-brake

Swagger contract checker for breaking API changes
Apache License 2.0
58 stars 16 forks source link

Add ability to allow removal of deprecated APIs #17

Closed dalewking closed 5 years ago

dalewking commented 5 years ago

Add ability to allow removal of an API previously marked as deprecated

dalewking commented 5 years ago

Thanks for adding this, but you probably should add a configuration option to enable this. Some people feel that APIs should never be deleted.

galovics commented 5 years ago

@dalewking thanks for reporting it first of all. :-) The OpenAPI spec allows you to deprecate APIs using the deprecated attribute on operation level. See the spec here: https://swagger.io/specification/#fixed-fields-8

Swagger Brake will check for this flag. If the old API is marked as deprecated and it got removed in the new version of the API, it won't be considered a breaking change anymore.

dalewking commented 5 years ago

I know all of that but deprecation simply means that people should no longer use it. Actually deleting it is a breaking change and according to some (e.g. https://api-university.com/api-lifecycle/api-design/api-design-api-evolution-api-versioning/) you should never make breaking changes and would have trouble with this being the default. So it would be best to add an option to enable this behavior

galovics commented 5 years ago

From my point of view, if anyone deletes an API which is already marked as deprecated, it might get deleted without any problem. Of course if people doesn't give the necessary time for the clients to switch from API1 to API2, it might get messy. Although a switch might be useful just to have the possibility for changing this behavior. I'll add it and make the behavior default and one can override it to explicitly mark that deprecated API deletion is not allowed.