Tufin / oasdiff

OpenAPI Diff and Breaking Changes
https://www.oasdiff.com
Apache License 2.0
735 stars 62 forks source link

Support x-sunset/deprecated at parameter level #627

Open pledesert-sg opened 2 weeks ago

pledesert-sg commented 2 weeks ago

Is your feature request related to a problem? Please describe. It may be necessary to remove an optional field. openapi support parameter deprecation, but oasdiff ignores it.

Describe the solution you'd like Treat parameter deprecation the same as route deprecation, (a parameter should have an associated x-sunset valid with the route grace period)

Describe alternatives you've considered Alternative will be to use oneOf and deprecation of schema, but it is even trickier for oasdiff (migrating existing schema to oneOf is considered a breaking change). Other alternative is to deprecate the whole route, and create a new route with version, but it is not optimal and respectful of REST principles.

Additional context orig.yml:

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

deprecate.yml:

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  deprecated: true
                increment:
                  type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

deprecated_with_sunset.yml

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  deprecated: true
                  x-sunset: '2022-10-01'
                increment:
                  type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

removed.yml

openapi: '3.0.3'
info:
  title: API Title
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /echo:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                increment:
                  type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

$ oasdiff breaking --fail-on WARN orig.yml deprecate.yml ; echo $?

0

-> no sunset, expected missing sunset warning


$  oasdiff breaking --fail-on WARN deprecated_with_sunset.yml removed.yml ; echo $?
1 changes: 0 error, 1 warning, 0 info
warning [request-property-removed] at removed.yml
        in API POST /echo
                removed the request property 'message'

1
reuvenharrison commented 2 weeks ago

Hi @pledesert-sg You are right. Deprecation is currently supported only for endpoints. Supporting deprecation for schemas would require adapting the endpoint deprecation code to schemas. Maybe someone from the community wants to pick this up?

Thanks, Reuven