openapi 3.1: swagger-parser won't parse a 3.1 spec

[gscott]

openapi 3.1 is released -- but the openapi-glue dependency https://github.com/APIDevTools/swagger-parser won't parse that spec . The repo over there appears slightly dormant. Any plans here for handling that dependency? Or should we try to do PRs on swagger-parser?

[seriousme]

Hi,

I was already waiting for swagger-parser to support 3.1
However swagger-parser indeed looks rather dormant :-(
If you can get it to wake up again that would be rather awesome !
If not we will need to come up with an alternative.

Kind regards,
Hans

[seriousme]

FYI:
Just noticed that the openAPI team is still busy producing the 3.1 JSON schema
OAI/OpenAPI-Specification#2474

This might wake up APIdevtools as its schema defs seem to rely on the official spec
See https://github.com/APIDevTools/openapi-schemas

[philsturgeon]

Give it a minute, we're on it. We need to get the OASv3.1 schema done so that other tools, like swagger-parser, can use it to get up to 3.1 support. It'll take a while before the tools you like are on 3.1, so please be patient, and send PRs whenever you can to help! 🥳

[seriousme]

@philsturgeon No rush, I'd rather see a solid schema than a rush job that needs to be patched 5 times over ;-)

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days'

[philsturgeon]

Progress on the schemas is going rather well. Maybe you could give it a try and report any problems over there. OAI/OpenAPI-Specification#2489

[seriousme]

@philsturgeon : thanks for reporting your progress !
Fastify-openapi-glue does not use the spec directly but through a dependency called APIDevTools/swagger-parser that in turn depends on APIDevTools/openapi-schemas and that one depends on your schema.

From the looks of it APIDevTools/openapi-schemas will automatically pick your schema up once its published.

Kind regards,
Hans

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days'

[seriousme]

Small update:

I have submitted a PR to APIDevTools/openapi-schemas 5 days ago. However no response yet :-(

If it turns out APIDevTools/* has been abandoned then we need to go for plan B.
I have been playing around a bit and it should not be too hard to remove the dependency on APIDevTools/swagger-parser.

Kind regards,
Hans

[philsturgeon]

I don't get the emails about it but I do have enough permissions to merge. Let me look into how to tag releases.

[seriousme]

Small update:

Plan A is moving very slowly. Phil has merged the 3.1 PR to APIdevTools/openapi-schemas (thanks for that !), but it has not been published yet on NPM.
My plan B was to do schema validation myself using Ajv however it looks like AJV has an issue with $dynamicRef in the OAS 3.1 specification. The issue is under investigation with the author of Ajv.

Kind regards,
Hans

[seriousme]

Another update:

Plan A: continue using swagger-parser

• @APIdevTools/swagger-parser supports v3.1
  • @APIdevTools/swagger-parser has working CI (I submitted a PR for that)
  • code fix is available to add 3.1 (https://github.com/seriousme/swagger-parser/tree/openApi-v3.1)
  • @APIdevTools/swagger-parser dependencies support v3.1
    • package @APIdevTools/openapi-schemas supports v3.1 (I submitted a PR for that resulting in version 2.1.0)
    • package zschema does not seem to support json-schema-draft-202012 which is required for v3.1
    • package openapi-types does not support v3.1

Plan B: build own openApi schema validator on Ajv

• have openapi schemas available for 2.0, 3.0 and 3.1
• make them work with Ajv 8.x
  • 2.0, by converting from draft-04 to draft-07
  • 3.0, by converting from draft-04 to draft-07
  • 3.1 not working since AJV has an issue with the $dynamicRef in the v3.1 specification

Given the number of dependencies Plan B seems the most viable candidate for now.

To be continued..

[seriousme]

Plan B seems to work :-)

Plan B: build own openApi schema validator on Ajv

• have openapi schemas available for 2.0, 3.0 and 3.1
• make them work with Ajv 8.x
  • 2.0, by converting from draft-04 to draft-07
  • 3.0, by converting from draft-04 to draft-07
  • 3.1, by converting $dynamicRef and $dynamicAnchor into $ref and $anchor for now. This might cause some limitations for now but I think thats worth it.

The result is https://github.com/seriousme/openapi-schema-validator and has way less dependencies than swagger-parser while swagger-parser also only checked for schema compliance on 3.0.

Next stop is integrating it with fastify-openapi-glue.

[seriousme]

It has been quite a journey but I just released version 2.6.0 that supports OpenApi 3.1.
With the new setup without swagger-parser it should also be easier to follow newer OpenApi versions.

Kind regards,
Hans

[gscott]

@seriousme Thank you so much; I know it was quite a treasure hunt to sort through all the paths but it looks like you've removed some dependencies which may be helpful going forward. I tested on my admittedly simple 3.1 spec and so far, it works beautifully! Again, thanks.