openapi-changes icon indicating copy to clipboard operation
openapi-changes copied to clipboard

Published 20 hours ago • verified publisher icon pb33f

Should `tags` changes be considered breaking?

Open tillig opened this issue 2 years ago • 4 comments

If you change an OpenAPI spec to rename a tag on an operation, currently the change to the tag will be reported as "breaking" for the contract.

While I can see that if I modify an operation or a model, I'm not sure how changing the tags on an operation could be breaking. I'm curious if tags changes should be marked informational instead.

tillig avatar Jun 22 '23 18:06 tillig

Tags are used by documentation and code-generation tools to group operations. Change a tag, change a whole lot of links and code. That's why it's breaking because it will change signatures somewhere.

daveshanley avatar Jun 22 '23 20:06 daveshanley

I mean, I guess that's breaking for something that isn't the service contract, but when I run a breaking changes checker for an OpenAPI contract it isn't readily apparent that it's going to consider things that aren't contractual to be breaking.

Is there an opportunity to make that optional? Like, "only mark contract-based changes as breaking?" Or maybe reduce it to a warning status or something?

tillig avatar Jun 22 '23 20:06 tillig

Unfortunately, there isn't a rules engine for determining what should and should not be considered breaking. It was designed as an opinionated engine.

Sounds like it should be something to add as a feature however.

daveshanley avatar Jun 27 '23 20:06 daveshanley

Changes to operations tags have been marked as 'breaking' in v0.0.52.

When this feature is available, this should become configurable.

daveshanley avatar Jan 05 '24 14:01 daveshanley