OpenAPITools / openapi-diff

Utility for comparing two OpenAPI specifications.
Apache License 2.0
787 stars 152 forks source link

Removing a Query parameter is considered a breaking change while removing a Request Body parameter isn't #412

Open AdamBosseBS opened 1 year ago

AdamBosseBS commented 1 year ago

While testing this tool, we've noticed that removing a query parameter would give a API changes broke backward compatibility result while removing a request body parameter would return a API changes are backward compatible. Shouldn't both be breaking changes?

If this is expected, we'd be curious to understand why that is.

Here are the spec files we used to test this:

image

old_queryparameter.yml :

openapi: "3.0.1"
info:
  title: "Public Api"
  description: ""
  version: "2022-08-23T16:17:54Z"
servers:
  - url: "https://someurl"
    variables:
      basePath:
        default: "/v1"
paths:
  /auth:
    post:
      parameters:
        - name: "Username"
          in: "query"
          required: true
          schema:
            type: "string"
        - name: "Password"
          in: "query"
          required: true
          schema:
            type: "string"

new_queryparameter.yml :

openapi: "3.0.1"
info:
  title: "Public Api"
  description: ""
  version: "2022-08-23T16:17:54Z"
servers:
  - url: "https://someurl"
    variables:
      basePath:
        default: "/v1"
paths:
  /auth:
    post:
      parameters:
        - name: "Username"
          in: "query"
          required: true
          schema:
            type: "string"

image

old_requestbody.yml:

openapi: "3.0.1"
info:
  title: "Public Api"
  description: ""
  version: "2022-08-23T16:17:54Z"
servers:
  - url: "https://someurl"
    variables:
      basePath:
        default: "/v1"
paths:
  /auth:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthRequest"
        required: true

components:
  schemas:
    AuthRequest:
      required:
        - "Username"
        - "Password"
      type: "object"
      properties:
        Username:
          type: "string"
        Password:
          type: "string"

new_requestbody.yml:

openapi: "3.0.1"
info:
  title: "Public Api"
  description: ""
  version: "2022-08-23T16:17:54Z"
servers:
  - url: "https://someurl"
    variables:
      basePath:
        default: "/v1"
paths:
  /auth:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthRequest"
        required: true

components:
  schemas:
    AuthRequest:
      required:
        - "Username"
      type: "object"
      properties:
        Username:
          type: "string"

Thank you!