Repository navigation
Comparing OpenAPI 3.0.1 to 3.1.0 does not work #755
Description
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.
Activity
DrSatyr commentedon Mar 16, 2025
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 commentedon Mar 17, 2025
Thanks for the info.
Didn't realize that Docker latest would include beta versions - wouldn't a beta tag be better for that?
DrSatyr commentedon Mar 17, 2025
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 commentedon Apr 9, 2025
Why is supporting the latest specification, that exists for over 4 years now, not the top most priority. That makes absolutely no sense.
DrSatyr commentedon Apr 10, 2025
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.