OpenAPI 변경 비교

OpenAPI Diff

두 OpenAPI 문서를 비교해 호환성을 깨는 변경과 추가만 된 변경을 구분해 보여 줍니다.

OpenAPI 문서 두 판본을 비교해서 변경을 호환성이 깨지는 것과 더해지는 것으로 나눕니다. 쓰는 기준은 페이지에 적혀 있습니다. 이전 문서가 받아 주던 요청이 이제 거부될 수 있거나, 이전 문서가 약속한 응답을 기존 클라이언트가 다룰 수 없게 되면 깨진 것입니다.

🔒 브라우저 안에서만 처리openapidiffapibreaking-change

이전 문서

openapi: 3.0.3
info: { title: Pets API, version: "1.0.0" }
paths:
  /pets:
    get:
      operationId: listPets
      summary: List pets
      parameters:
        - name: limit
          in: query
          schema: { type: integer }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Pet" }
  /pets/{id}:
    get:
      operationId: getPet
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pet" }
        "404": { description: Not found }
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id: { type: integer }
        name: { type: string }
        status: { type: string, enum: [available, sold] }

이전 버전 파일 놓기

이 탭 안에서만 읽습니다.

새 문서

openapi: 3.0.3
info: { title: Pets API, version: "2.0.0" }
paths:
  /pets:
    get:
      operationId: listPets
      summary: List pets, paginated
      parameters:
        - name: limit
          in: query
          required: true
          schema: { type: integer }
        - name: sort
          in: query
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Pet" }
  /pets/{petId}:
    get:
      operationId: getPet
      parameters:
        - { name: petId, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Pet" }
    delete:
      operationId: deletePet
      parameters:
        - { name: petId, in: path, required: true, schema: { type: string } }
      responses:
        "204": { description: Deleted }
components:
  schemas:
    Pet:
      type: object
      required: [id]
      properties:
        id: { type: string }
        name: { type: string }
        status: { type: string, enum: [available, sold, pending] }
        owner: { $ref: "#/components/schemas/Owner" }
    Owner:
      type: object
      properties:
        name: { type: string }

새 버전 파일 놓기

이 탭 안에서만 읽습니다.

호환성 깨짐

추가·보완

판정

메이저 버전 올려야 함

GET /pets

깨짐`in: query`의 `limit` 파라미터가 필수가 됐습니다.
추가`in: query`의 `sort` 선택 파라미터가 추가됐습니다.
변경요약이나 설명이 달라졌습니다.

GET /pets · responses["200"].content["application/json"]

깨짐`[].id`의 타입이 integer에서 string으로 바뀌었습니다.
깨짐`[].name` 속성이 선택이 됐습니다.
깨짐`[].status`의 enum에 "pending" 값이 추가됐습니다.
추가`[].owner` 선택 속성이 추가됐습니다.

GET /pets/{petId} · responses["200"].content["application/json"]

깨짐`id`의 타입이 integer에서 string으로 바뀌었습니다.
깨짐`name` 속성이 선택이 됐습니다.
깨짐`status`의 enum에 "pending" 값이 추가됐습니다.
추가`owner` 선택 속성이 추가됐습니다.

GET /pets/{petId}

깨짐`404` 응답이 사라졌습니다.

DELETE /pets/{petId}

추가작업이 추가됐습니다.

components.schemas.Owner

추가스키마가 추가됐습니다.

info.version

변경`1.0.0` → `2.0.0`

호환성이 깨진다고 판단하는 규칙

한 문장으로: 이전 문서가 받아 주던 요청이 거부될 수 있거나, 이전 문서가 약속한 응답을 기존 클라이언트가 못 다루게 되면 깨진 것입니다. 그래서 경로·작업·응답 코드·미디어 타입·응답 속성의 제거, 필수 파라미터·필수 요청 속성의 추가, 선택→필수, 타입 변경, 요청 enum 값 제거, 응답 enum 값 추가(클라이언트의 switch에 case가 없습니다), 응답 속성의 필수→선택은 깨짐이고, 그 반대 방향과 설명·태그·operationId·deprecated 표시는 호환입니다.

· 스키마는 문서 안의 $ref를 따라간 뒤 비교하므로 컴포넌트 이름만 바꾼 것은 변경이 아닙니다. 경로 파라미터도 이름이 아니라 위치로 맞춥니다.
· oneOf·anyOf·not 안은 통째로 비교해 달라졌으면 깨짐으로 표시합니다. 안쪽까지 들어가 판단하지는 않습니다.
· 다른 파일을 가리키는 $ref는 따라가지 않습니다. 파일을 하나로 합쳐서 넣으세요.

문서 하나를 점검하려면 OpenAPI 점검을 쓰세요.

사용 방법

이전 문서와 새 문서를 나란히 놓습니다
둘 다 JSON이든 YAML이든 됩니다. 이 탭에서 파싱하므로 아직 공개하지 않은 명세가 기계 밖으로 나가지 않습니다.
판정을 읽습니다
깨지는 변경과 더해지는 변경의 개수, 그리고 그것이 버전 번호에 무엇을 뜻하는지가 나옵니다. 메이저를 올릴지, 마이너면 되는지, 계약이 그대로라 올릴 것이 없는지입니다.
깨지는 것만 걸러서 읽습니다
작업별로 묶여 있고 무엇이 바뀌었는지가 붙어 있습니다. 마크다운 복사는 풀 리퀘스트 설명에 넣기 좋은 형태입니다.