docusaurus-openapi-docs
docusaurus-openapi-docs copied to clipboard
PaloAltoNetworks
OpenAPI 3.1 support?
Is your feature request related to a problem?
I was trying to use open api 3.1.0 syntax, but it seems to be causing problems, so maybe it's not supported?
Describe the solution you'd like
Support 3.1.0
Additional context
Is it already supported and I'm just using it wrong? I do see Compatible: Works with Swagger 2.0 and OpenAPI 3.x. in the website, but when I tried to use type: [string, 'null'], the resulting span was just stringnull smashed together like that, whereas nullable: true added a nice nullable tag.
Hi @IanVS, OpenAPI 3.1 definitely isn't supported, yet. FWIW, there are tools that will down convert to from 3.1 to 3.0 but there could be loss of features in the process. That said, our plugin does attempt to resolve all JSON schema $ref pointers, regardless of whether or not they follow the OpenAPI spec.
Thanks for confirming. What would you think about making that clearer in the README? Maybe just change 3.x to 3.0?
3.1 would be really appreciated because you can now have a separate top level element for describing WebHooks
What would you think about making that clearer in the README? Maybe just change 3.x to 3.0?
I agree, that could definitely help make it clearer.
Hi @stefan-schweiger, support for 3.1 is on the roadmap. We're hoping to have it ready for our v2.0.0 release in the next 2-3 months.
looks like this'll be a post-2.0 update? I can imagine it's some work to support multiple OpenAPI versions.
Hi @jasikpark, it really depends. We use external libraries for parsing so it would really come down to:
- How well those libraries support OpenAPI 3.1
- Which unique OpenAPI 3.1 features we decide to support and how compatible those features are with existing UI
ok! thx for breaking that down - maybe this issue can contain the status of those deps
Hi @sserrata, have you given any more thought to openapi 3.1 support? In specific, I'm wishing we had the ability to describe the shape of dynamic keys on objects: https://github.com/OAI/OpenAPI-Specification/issues/1505.
Hi @IanVS, I checked and there is a more recent release of @redocly/openapi-core that we can upgrade to. I tested a few OpenAPI 3.1 specs with our plugin and it appears to offer some support, although I can't guarantee 100% support/coverage of all 3.1 features.
Hi @IanVS, I was wondering if you've had a chance to test the new @redocly/openapi-core parser?
Not yet, though I hope to before too long. I'm a bit behind on upgrades and it's going to take a lot of reworking of our custom CSS to update to the latest plugin versions. Was kind of holding off until there was word that docusaurus 3 is fully supported, which would give us even more reason to upgrade.
Hi @sserrata I finally updated to 3.0 of the plugin, and tried using openapi 3.1, but the issue remains that I described at the top of this issue, that using [string, 'null'] results in stringnull instead of a nullable tag. Would you like a separate issue for that?
Added an issue for that specific bug: https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/950