Comparing OpenAPI 3.0.1 to 3.1.0 does not work

[codesimplicity]

When running a comparison between OpenAPI 3.0.1 and 3.1.0 via Docker, it looks like everything is reported as different.

Suppressing the details gives this:

$ docker run --rm -t -v .:/specs:ro  openapitools/openapi-diff /specs/api-docs-301.json /specs/api-docs-310.json --state
incompatible

ℹ Please note that those spec files are identical, only the initial OpenAPI version differs:

• "openapi": "3.0.1"
• "openapi": "3.1.0"

Comparing two specs with OpenAPI 3.1.0 seems to work as desired. ✅

I used latest which appears to be 6 weeks old - cannot get the version from the tool itself 🤷

---

Running the same via openapi-diff installed from brew shows a different error:

$ openapi-diff api-docs-301.json api-docs-310.json 
Unexpected exception. Reason: Cannot read new OpenAPI spec
java.lang.RuntimeException: Cannot read new OpenAPI spec
        at org.openapitools.openapidiff.core.OpenApiCompare.notNull(OpenApiCompare.java:107)
        at org.openapitools.openapidiff.core.OpenApiCompare.fromSpecifications(OpenApiCompare.java:102)
        at org.openapitools.openapidiff.core.OpenApiCompare.fromLocations(OpenApiCompare.java:91)
        at org.openapitools.openapidiff.cli.Main.main(Main.java:174)

But this also does not work with two OpenAPI 3.1.0 specs:

$ openapi-diff api-docs-310.json api-docs-310.json 
Unexpected exception. Reason: Cannot read old OpenAPI spec
java.lang.RuntimeException: Cannot read old OpenAPI spec

Brew shows this to be version 2.0.1 - cannot get the version from the tool itself.

[DrSatyr]

I used latest which appears to be 6 weeks old - cannot get the version from the tool itself 🤷

Yeah, good catch, "--version" flag does not work. I've created a fix #756

Regarding "latest" docker tag - it is latest beta build 2.1.0-beta12. But if you're using openapi-diff from brew, it has only a stable 2.0.1 release. So the behaviour is not the same.

Anyway, support of OpenAPI 3.1.0 is not officially supported by openapi-diff tool (regardless it works in some cases), we have only plans to support it fully #380. Unfortunately - it is not a priority for 2.1.0 release

[codesimplicity]

Thanks for the info.

Didn't realize that Docker latest would include beta versions - wouldn't a beta tag be better for that?

[DrSatyr]

Didn't realize that Docker latest would include beta versions - wouldn't a beta tag be better for that?

I agree, it would be better. Will check the docker release pipeline during the next release. It should not update the latest tag while the beta version released.

[T3rm1]

Unfortunately - it is not a priority for 2.1.0 release

Why is supporting the latest specification, that exists for over 4 years now, not the top most priority. That makes absolutely no sense.

[DrSatyr]

Unfortunately - it is not a priority for 2.1.0 release

Why is supporting the latest specification, that exists for over 4 years now, not the top most priority. That makes absolutely no sense.

Yep, it looks strange, but it is what we have now. Support 3.1.0 needs a lot of contributions; meanwhile, no contributors are willing to move 3.1.0 forward (to be honest, other initiatives are also in the same situation). My current ultimate goal is to finish and release 2.1.0, which contains a lot of improvements regarding 3.0.x support.

I would appreciate any contribution to the 3.1.0 support: https://github.com/OpenAPITools/openapi-diff/labels/OpenAP%203.1.0%20Support. So, there are 2 known related issues, but we need to determine what works right now and what does not. Then, provide fixes/improvements.