OpenAPITools / OpenAPITools/openapi-diff
False positive when adding optional property
オープン
まだ誰も着手していません。
Breaking/Non-Breaking classification
- 主要言語
- Java
- スター
- 1.1k
- フォーク
- 190
- PR マージ指標
- 30日以内にマージされた PR はありません
説明
When comparing these 2 schemas:
test/old.json
{
"openapi": "3.0.0",
"servers": [{ "url": "https://myserver.com" }],
"info": { "title": "My API", "description": "Description", "version": "0.2.0" },
"paths": {
"/v1/entity/{id}": {
"put": {
"operationId": "myOperation",
"description": "Some description",
"requestBody": { "$ref": "#/components/requestBodies/updateBody" }
}
}
},
"components": {
"schemas": {},
"responses": {},
"requestBodies": {
"updateBody": {
"description": "Update description",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": { "type": "string", "description": "Some URL" }
},
"title": "updateBody",
"additionalProperties": false
}
}
}
}
},
"parameters": {}
}
}
test/new.json
{
"openapi": "3.0.0",
"servers": [{ "url": "https://myserver.com" }],
"info": { "title": "My API", "description": "Description", "version": "0.2.0" },
"paths": {
"/v1/entity/{id}": {
"put": {
"operationId": "myOperation",
"description": "Some description",
"requestBody": { "$ref": "#/components/requestBodies/updateBody" }
}
}
},
"components": {
"schemas": {},
"responses": {},
"requestBodies": {
"updateBody": {
"description": "Update description",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": { "type": "string", "description": "Some URL" },
"url2": { "type": "string", "description": "Some URL" }
},
"title": "updateBody",
"additionalProperties": false
}
}
}
}
},
"parameters": {}
}
}
I get a broken compatibility message:
docker run --rm -t -v $(pwd)/test/:/specs:ro openapitools/openapi-diff:latest --fail-on-incompatible /specs/old.json /specs/new.json
==========================================================================
== API CHANGE LOG ==
==========================================================================
My API
--------------------------------------------------------------------------
-- What's Changed --
--------------------------------------------------------------------------
- PUT /v1/entity/{id}
Request:
- Changed application/json
Schema: Broken compatibility
--------------------------------------------------------------------------
-- Result --
--------------------------------------------------------------------------
API changes broke backward compatibility
--------------------------------------------------------------------------
Note that the only change is the addition of the url2 optional property:
diff -u test/old.json test/new.json
--- test/old.json 2023-03-14 17:06:02
+++ test/new.json 2023-03-14 17:06:33
@@ -22,7 +22,8 @@
"schema": {
"type": "object",
"properties": {
- "url": { "type": "string", "description": "Some URL" }
+ "url": { "type": "string", "description": "Some URL" },
+ "url2": { "type": "string", "description": "Some URL" }
},
"title": "updateBody",
"additionalProperties": false
Since the required field is absent, I would expect the addition of url2 to not create a broken compatibility error.
コントリビューションガイド
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
調査の方向性
提供されたtest/old.jsonとtest/new.jsonのfixtureから始め、レポートに記載されたDockerコマンドを使って結果を再現します。必須フィールドのない追加プロパティに対するリクエストボディスキーマの互換性チェックを追跡し、その後リグレッションテストを追加して、比較結果で後方互換性のない変更が報告されなくなったことを確認します。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- java
- 領域
- api
- issue の種類
- バグ
- 難易度
- 3/5
- 見積もり時間
- 1〜2日
- 活発さ
- 停滞
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 42/100