Skip to content

Support Swagger 2.0 through --auto-upgrade, and refuse it without the flag #1311

Open

Description

@reuvenharrison

Problem

oasdiff reads every file as OpenAPI 3.x. A Swagger 2.0 file is not rejected: it is parsed as an OpenAPI 3 document with no openapi field, its definitions end up as an extension, and its in: body parameters are not request bodies. breaking and changelog then find nothing to check and print "No changes to report" with exit code 0, so a breaking change passes CI silently (#1306). diff shows structural differences, and validate reports the missing openapi field and the invalid parameter location, but neither is what a user comparing two 2.0 specs looks at.

Proposal

  1. Convert Swagger 2.0 with --auto-upgrade. diff, breaking, changelog and summary already accept --auto-upgrade, which canonicalizes both specs to the latest OpenAPI 3.x after loading. Extend it to convert a Swagger 2.0 document first, using kin-openapi's openapi2conv.ToV3, and extend the upgrade command the same way (docs/OPENAPI-31.md currently says Swagger 2.0 to 3.0 is out of scope).
  2. Refuse Swagger 2.0 without the flag. When a loaded document is Swagger 2.0 (a top-level swagger key) and --auto-upgrade is not set, exit with an error that says Swagger 2.0 is not compared directly and names the flag, instead of comparing it as OpenAPI 3.

On the #1306 example, converting both files with openapi2conv.ToV3 and comparing them reports new-required-request-property for status and request-property-became-optional for value, which is the expected result.

To decide

  • Source locations. The converted document is not the text the user wrote, so locations would point into the conversion. Annotations (--format githubactions) and the review need locations in the original file; either map them back where kin's origin tracking survives conversion, or degrade them to the file, and say so.
  • Messages. Changes would describe OpenAPI 3 shapes (a request body) for a spec that has a body parameter. A short note that the spec was converted may be enough.
  • Conversion fidelity. openapi2conv has its own edge cases (kin-openapi carries many regression tests for it). Fixes belong upstream in kin-openapi.
  • Mixed versions. A 2.0 base against a 3.x revision should work with the flag, as 3.0 against 3.1 does today.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions