Support rendering OpenAPI and Swagger documents

[lunny]

Fix #20852

At the beginning, I want to use iframe but finally I found it'd difficult to implement it safely. So the new idea is open a new page to render the file.

There will be a placeholder button

And click the button will redirect to the real render page.

[silverwind]

No, the current approach is not right. We should load swagger-ui-dist from JS code, with the backend only signalling via HTML attribute that the content is to be rendered as openapi, very similar to the PDF rendering.

To achieve this, put the same dynamic import in both web_src/js/standalone/swagger.js and the new web_src/js/render/swagger.js:

const [{default: SwaggerUI}] = await Promise.all([
  import(/* webpackChunkName: "swagger-ui" */'swagger-ui-dist/swagger-ui-es-bundle.js'),
  import(/* webpackChunkName: "swagger-ui" */'swagger-ui-dist/swagger-ui.css')
]);

Having the exact same block will allow webpack to dedupe the chunks.

Also, I'm pretty sure we want to contain swagger-ui's CSS into an <iframe> because otherwise it will wreak havoc on our styles, but let's take it one step at a time.

[silverwind]

Changed the title. This should support OpenAPI up to 3.1, and all Swagger versions.

[wxiaoguang]

If the rendered content contains user's javascript, would allow-same-origin cause XSS?

[silverwind]

Iframe with sandbox attributes allow-scripts allow-same-origin allows the embedee to remove the sandbox attribute. From MDN:

When the embedded document has the same origin as the embedding page, it is strongly discouraged to use both allow-scripts and allow-same-origin, as that lets the embedded document remove the sandbox attribute — making it no more secure than not using the sandbox attribute at all.

Not that I see a big issue here because openapi specs can not contain executable code.

[wxiaoguang]

But this code is for all renders, not only for OpenAPI.

[silverwind]

For PDF renderer, it can definitely be an issue as those could maybe contain JS.

[silverwind]

So if the iframe really needs allow-same-origin, we should specifically allow it only for the openapi renderer, otherwise remove the attribute. In fact, I strongly prefer removal to avoid future security issues.

[lunny]

The current swagger.js just supports 2.0 specification and just support JSON file. It needs to be changed to support 3.0 specification and YAML file.

[silverwind]

The current swagger.js just supports 2.0 specification and just support JSON file. It needs to be changed to support 3.0 specification and YAML file.

We use the latest swagger-ui available (from npm), so it should support everything up to openapi 3.1, json or yaml.

[silverwind]

I'll give this a review/test soon.

[silverwind]

Hmm I do get Uncaught (in promise) TypeError: can't access property "sort", spec.schemes is undefined when I try to view this openapi 3.1 document. Also, the "open in new page" needs to be removed, we can embed the iframe.

[silverwind]

Hmm I do get Uncaught (in promise) TypeError: can't access property "sort", spec.schemes is undefined when I try to view this openapi 3.1 document. Also, the "open in new page" needs to be removed, we can embed the iframe.

Fixed it with 897be68, now openapi 3.1 renders fine.

[silverwind]

d866b87 makes it work for yaml specs as well. Had to add the yaml parser dependency as swagger-ui can only process js objects.

[silverwind]

TODOs:

• Embed in iframe
• Inherit dark/light theme from parent page

[silverwind]

Oops, I think I destroyed this PR with some force-push action (it wouldn't let me push my latest commit even after ensuring I was on tip multiple times via reset and branch re-creation).

New PR to continue: #26802