OpenAPITools / OpenAPITools/openapi-diff
Refactoring a schma with "$ref" results in false positive breaking change
还没有人认领这个 Issue。
- 主要语言
- Java
- 星标
- 1.1k
- 派生
- 190
- PR 合并指标
- 30 天内没有已合并 PR
描述
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.
贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
调研方向
使用提供的 old.yaml 和 new.yaml 通过文档中的 docker run 命令重现该报告,然后跟踪 schema 比较和 $ref/allOf 解析路径。当等效 schema 仍能生成变更报告且没有 breaking-compatibility 结果时,即视为完成;如果现有测试布局提供了合适的位置,请为此示例添加覆盖。
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- java
- 领域
- api
- Issue 类型
- 缺陷
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 活跃度
- 停滞
- 描述清晰度
- 基本清楚
- 新手友好度
- 40/100