OpenAPITools / OpenAPITools/openapi-diff

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

オープン
#192 コメント 1 件 リアクション 14 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

Breaking/Non-Breaking classification help wanted
主要言語
Java
スター
1.1k
フォーク
190
PR マージ指標
30日以内にマージされた PR はありません

説明

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.

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

提供された old.yaml と new.yaml を、ドキュメントに記載された docker run コマンドで使ってレポートを再現し、その後、スキーマ比較と $ref/allOf 解決の経路を追跡します。相当するスキーマが引き続き、互換性を壊す結果なしで変更レポートを生成すれば完了です。既存のテスト構成に適切な配置場所がある場合は、この例のカバレッジを追加してください。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
java
領域
api
issue の種類
バグ
難易度
4/5
見積もり時間
3〜5日
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
40/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。