OpenAPITools / OpenAPITools/openapi-diff

False positive when adding optional property

Ouverte
#490 3 commentaires 1 réaction 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Breaking/Non-Breaking classification
Langage dominant
Java
Étoiles
1.1k
Forks
190
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

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.

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez avec les fixtures fournis test/old.json et test/new.json et reproduisez le résultat à l’aide de la commande Docker indiquée dans le rapport. Suivez la vérification de compatibilité du schéma du corps de la requête pour une propriété ajoutée sans champ obligatoire, puis ajoutez un test de régression et confirmez que la comparaison ne signale plus de changement rétro-incompatible.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
java
Domaine
api
Type d'issue
Bug
Difficulté
3/5
Temps estimé
1-2 jours
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
42/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.