OpenAPITools / OpenAPITools/openapi-diff

Consider removal of deprecated elements as compatible

Open
#371 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Breaking/Non-Breaking classification
Dominant language
Java
Stars
1.1k
Forks
190
PR merge metrics
No merged PRs in 30d

Description

I'm using openapi-diff quite successfully to avoid accidental changes in the API (and therefore introducing a breaking change). We use it as a part of our pipeline.

The current struggle is: that sometimes one wants to introduce a breaking change (like the removal of obsolete API).
My initial idea would float around a two-step process:

  • marking an element ad deprecated (keeping compatibility)
  • removing the deprecated element

To do that, when processing the list of ChangedOpenApi#getChangedElements I'd need to know if the particular element is deprecatable and decide if the change is incompatible or not.

That looks to me like another SPI but I'm not sure if it's the direction. I know it's currently not possible and I'm not even sure if the direction of my thought even makes sense.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by examining ChangedOpenApi#getChangedElements and how openapi-diff currently classifies removals as incompatible. Review the existing extension points and the issue's proposed SPI idea before deciding on an approach. Done should provide a clear way to treat removal of deprecated elements as compatible while preserving the existing breaking-change checks.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.