OpenAPITools / OpenAPITools/openapi-diff

Refactoring a schma with "$ref" results in false positive breaking change

Ouverte
#192 1 commentaire 14 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

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

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.

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

Reproduisez le rapport avec les fichiers old.yaml et new.yaml fournis à l’aide de la commande docker run documentée, puis suivez le chemin de comparaison des schémas et de résolution de $ref/allOf. C’est terminé lorsque les schémas équivalents produisent toujours un rapport de modifications sans résultat de compatibilité rompue ; ajoutez une couverture pour cet exemple si la structure de tests existante offre un emplacement approprié.

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é
4/5
Temps estimé
3-5 jours
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
40/100

Recevez les nouvelles issues par e-mail

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