OpenAPITools / OpenAPITools/openapi-diff

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

Đang mở
#798 4 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Breaking/Non-Breaking classification
Ngôn ngữ chính
Java
Star
1.1k
Fork
190
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

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.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu với các tệp base.yml và revision.yml được cung cấp, rồi chạy openapi-diff breaking base.yml revision.yml để tái hiện kết quả tương thích đã báo cáo. Lần theo đường dẫn so sánh schema cho thuộc tính response id, sau đó bổ sung coverage cho thấy việc thu hẹp oneOf thành type: integer được chấp nhận và không có kết quả breaking change nào được báo cáo.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
java
Lĩnh vực
api
Loại issue
Lỗi
Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
48/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.