search

OpenAPITools / openapi-diff

Utility for comparing two OpenAPI specifications.
Apache License 2.0
784 stars 153 forks source link

False positive when adding optional property #490

Open spg opened 1 year ago

spg commented 1 year ago

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.

joschi commented 1 year ago

I think this was originally introduced in https://github.com/OpenAPITools/openapi-diff/issues/136 / https://github.com/OpenAPITools/openapi-diff/issues/137.

Happy to discuss whether it still makes sense.

mas-chen commented 1 year ago

https://www.rfc-editor.org/rfc/rfc7231#section-4.3.4

The RFC does say "SHOULD" and not "MUST" so I believe it would be good to make this strict check configurable

mas-chen commented 1 year ago

There's similar issues here: https://github.com/OpenAPITools/openapi-diff/issues/251 and https://github.com/OpenAPITools/openapi-diff/issues/264