OpenAPITools / OpenAPITools/openapi-diff
Refactoring a schma with "$ref" results in false positive breaking change
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 1.1k
- Forks
- 190
- PR merge metrics
- No merged PRs in 30d
Description
The bug
When splitting a schema into two schemas where one refers with allOf to the other the diff shows breaking change, even if the end structure is the same.
To Reproduce
Example schema old.yaml:
openapi: "3.0.0"
info:
title: Sample API
description: API description in Markdown.
version: 1.0.0
servers: []
paths:
/test:
get:
summary: Your GET endpoint
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/working'
components:
schemas:
working:
type: object
properties:
foo:
type: string
bar:
type: integer
Example schema new.yaml:
openapi: 3.0.0
info:
title: Sample API
description: API description in Markdown.
version: 1.1.0
servers: []
paths:
/test:
get:
summary: Your GET endpoint
tags: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/working'
operationId: get-test
components:
schemas:
working:
allOf:
- type: object
properties:
foo:
type: string
- $ref: '#/components/schemas/bar'
bar:
type: object
properties:
bar:
type: integer
Result of docker run -v $(pwd):/tmp openapitools/openapi-diff:latest /tmp/old.yaml /tmp/new.yaml:
==========================================================================
== API CHANGE LOG ==
==========================================================================
Sample API
--------------------------------------------------------------------------
-- What's Changed --
--------------------------------------------------------------------------
- GET /test
Return Type:
- Changed 200 OK
Media types:
- Changed application/json
Schema: Broken compatibility
Changed property type: (object -> object)
--------------------------------------------------------------------------
-- Result --
--------------------------------------------------------------------------
API changes broke backward compatibility
--------------------------------------------------------------------------
Expected behavior
The tool is expected to notice a change but not a breaking one since the allOf mapping results in the same schema after resolving.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the report with the provided old.yaml and new.yaml using the documented docker run command, then trace the schema comparison and $ref/allOf resolution path. Done means the equivalent schemas still produce a change report without a breaking-compatibility result; add coverage for this example if the existing test layout provides a suitable location.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 40/100