[plugin-api-docs] Support OpenAPI 3.1

[johanneswuerbach]

Feature Suggestion

Support rendering openapi: 3.1.x API definitions in Backstage. OpenAPI 3.1.0 was released as stable in the beginning of the year.

Possible Implementation

This likely depends on swagger-ui supporting OpenAPI 3.1, which it doesn't yet swagger-api/swagger-ui#5891, but it might be a good preparation to update to swagger-ui v4 already as only v4 will get OpenAPI 3.1 support.

Context

Current backstage view when looking at an OpenAPI 3.1 schema:

[freben]

Makes sense! Is this something you might be able to work on?

[freben]

I see that we depend on "swagger-ui-react": "^4.0.0-rc.3" in the API plugin. Latest version of that as of this time is 4.1.0.

[Rugvip]

Yep, would make sense to update to the latest stable release, regardless of whether we get support for 3.1. Opening that up to contributions in case anyone wants to beat us to it 😁

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[floriank]

So,

Hey - since it'd be rather important to me (and the company) to get some movement on the OAS 3.1 front going, I've spent some time looking into this. The news is a bit bleak though:

1. Backstage depends on swagger-ui-react (see here)
2. swagger-ui-react currently does not support OAS 3.1, hence we get no API explorer for specs using that scheme version
3. The swagger authors decided to work on a new version of their editor first, which will resolve the issue

This unfortunately means either one of two things:

1. Sit and wait.
2. Replace the dependency with something like OpenAPI Explorer. I've no opinion on this package myself (and I am not associated).

Anyway, this issue therefore should probably no be a good first contribution 😉.

Cheers ❤️

[floriank]

(I also should've realized that @johanneswuerbach mentioned most of this in the original issue description, mea culpa 🤦)

[floriank]

In an effort to provide a tiny bit more substance, here is a branch where I switched out swagger-ui-react with openapi-explorer.

The result needs styling, obviously, but works rather nice, even with OAS 3.1:

Note of course that the spotify example is OAS 3.0.1, to test this out, I switched the OAS for the petstore to a OAS 3.1 version.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[johanneswuerbach]

Still relevant 👍

[EduSemensati]

Is anyone looking into this?

[floriank]

not actively, as I don't really have time myself. Switching out the OpenAPI Explorer is easy, but I am no CSS magician, so it'd look like 💩.

[jetslambda]

Personal opinion: Tests in Backstage are intended for React components making openapi-explorer hard to test since it is a 'Lit' component (Google.) I was able to integrate it and make it look good but I was unable to fiddle with it enough to get all tests passing. Swagger.io intends to have OpenAPI3.1 compatibility in swagger-ui this Quarter. I think we should wait a few weeks and implement the upcoming version of swagger-ui.

https://swagger.io/blog/swagger-support-for-openapi-3-0-and-openapi-3-1/

Swagger UI and Swagger Client 
Rendering for OpenAPI 3.1 will soon follow as part of our [Swagger UI](https://github.com/swagger-api/swagger-ui) enhancements. In a nutshell, the ability to process and render OpenAPI 3.1 definitions/documents within Swagger UI will be enabled by the integration of [ApiDOM](https://github.com/swagger-api/apidom) with [Swagger Client](https://github.com/swagger-api/swagger-js). 

We’re expecting to have this completed in Q1 2023 which will bring the rendering capability also into our Swagger Editor tool.

[jetslambda]

My implementation is here if anyone would like to do something with it:

backstage/plugins/api-docs/src/components/OpenApiDefinitionWidget/OpenApiDefinition.tsx

Line 27 in 88443dc

const theme: BackstageTheme = useTheme();

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[freakyfelt]

nudging to appease the stalebot

[pjungermann]

https://github.com/swagger-api/swagger-ui/labels/version%3A%205.x
and swagger-api/swagger-ui#8684 to watch for beta

[pjungermann]

FYI: swagger-ui v5.0.0 was released 2h ago.

@type/swagger-ui-react is still pending.

[pjungermann]

In case you didn't see it yet, the linked PR will resolve this issue. It contains two 3.1.0 examples as well. A release of the type package was not necessary, they are still compatible.

If reviews go through, it should be part of next week's main release.