OpenAPITools / OpenAPITools/openapi-diff

Changing response field type from `oneOf: string, number` to `string` shouldn't break

Offen
#798 4 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Breaking/Non-Breaking classification
Vorherrschende Sprache
Java
Sterne
1.1k
Forks
190
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

Describe the bug
In the response body, if you change the following field:

content:
  application/json:
    schema:
      properties:
        id:
          oneOf:
            - type: integer
            - type: string
      required:
        - id
      type: object

to:

content:
  application/json:
    schema:
      properties:
        id:
          type: integer
      required:
        - id
      type: object

Then openapi-diff reports this as a breaking change.

To Reproduce

base.yml
openapi: 3.0.1
info:
  title: User Service
  version: 1.0.0
paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: integer
              required:
                - name
        required: true
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                properties:
                  id:
                    oneOf:
                      - type: integer
                      - type: string
                required:
                  - id
                type: object
revision.yml
openapi: 3.0.1
info:
  title: User Service
  version: 1.0.0
paths:
  /users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: integer
              required:
                - name
        required: true
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                required:
                  - id
                type: object
  1. Download the two files base.yml and revision.yml
  2. Run openapi-diff breaking base.yml revision.yml
  3. Observe the following output:
==========================================================================
==                            API CHANGE LOG                            ==
==========================================================================
                               User Service
--------------------------------------------------------------------------
--                            What's Changed                            --
--------------------------------------------------------------------------
- POST   /users
  Return Type:
    - Changed 201 Created
      Media types:
        - Changed application/json
          Schema: Broken compatibility
          Changed property type: id (object -> integer)
--------------------------------------------------------------------------
--                                Result                                --
--------------------------------------------------------------------------
                 API changes broke backward compatibility
--------------------------------------------------------------------------

Expected behavior
openapi-diff shouldn't mark this as a breaking change. Actually, the response body should be considered as a covariant contract: narrowing a field type isn't a breaking change.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginnen Sie mit den bereitgestellten Dateien base.yml und revision.yml und führen Sie openapi-diff breaking base.yml revision.yml aus, um das gemeldete Kompatibilitätsergebnis nachzustellen. Verfolgen Sie den Schema-Vergleichspfad für die Response-Eigenschaft id, und fügen Sie dann Tests hinzu, die zeigen, dass das Eingrenzen von oneOf auf type: integer akzeptiert wird und kein Ergebnis für eine Breaking Change gemeldet wird.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
java
Bereich
api
Issue-Typ
Bug
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
48/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.