Site: restore inline Redoc rendering for API spec pages - #5434
Conversation
The `redoc-polaris` shortcode was originally designed to render the OpenAPI spec inline using the Redoc component. A later change (c3f0681) replaced the Redoc `<script>` tag with a `<meta http-equiv="refresh">`, causing the page to immediately redirect to the Swagger editor instead, leaving the Redoc component output unreachable and producing an abrupt browser experience. This commit restores inline rendering by bringing the shortcode back in line with the Docsy v0.14.3 original it was copied from, substituting only the URL resolution block with the Polaris-specific `rawGithubPolarisUrl` partial. A separate "Open in Swagger Editor ↗" link is added for users who prefer the editor, and the ↗ suffix is removed from the sidebar link titles since the pages no longer redirect.
There was a problem hiding this comment.
🟡 Changes recommended
The newly added Swagger Editor link uses HTTP and does not URL-encode the url= query parameter, which can cause mixed-content and URL-handling issues on HTTPS sites.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Restores inline Redoc rendering for Polaris OpenAPI spec documentation pages by reverting the redoc-polaris shortcode behavior back toward Docsy’s original approach (render inline, with an optional link out to Swagger Editor) and updating sidebar link titles to match the new non-redirect behavior.
Changes:
- Replace the shortcode’s redirect behavior with inline Redoc rendering via the Redoc standalone script.
- Add an “Open in Swagger Editor ↗” link instead of forcing an immediate redirect.
- Remove the ↗ suffix from API spec page
linkTitlevalues now that pages no longer redirect.
File summaries
| File | Description |
|---|---|
| site/layouts/shortcodes/redoc-polaris.html | Restores inline Redoc rendering and adds an explicit Swagger Editor link. |
| site/content/in-dev/unreleased/polaris-api-specs/polaris-management-api.md | Updates sidebar link title to remove ↗ since the page no longer redirects externally. |
| site/content/in-dev/unreleased/polaris-api-specs/polaris-catalog-api.md | Updates sidebar link title to remove ↗ since the page no longer redirects externally. |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| --> | ||
|
|
||
| <meta http-equiv="refresh" content="0; url=http://editor-next.swagger.io/?url={{ $url }}" /> | ||
| <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"></script> |
There was a problem hiding this comment.
(Re)adding Redoc rendering for API specs is nice!
This line however is concerning.
The current site build already fetches pinned jQuery and Lunr scripts, adding/using a pinned Redoc JS would resolve the concern.
There was a problem hiding this comment.
Agreed on serving a pinned Redoc bundle from the site, since the current CSP blocks this CDN script. That still leaves the YAML: Redoc fetches it from raw.githubusercontent.com, which is also blocked because connect-src falls back to default-src. Could we publish the correctly versioned specs with the site too, then verify that both API pages render under the production CSP?
flyingImer
left a comment
flyingImer
left a comment
There was a problem hiding this comment.
I'd hold off merging until the loading issue in the existing thread is resolved. The restored inline API docs need to work under the production CSP.
The
redoc-polarisshortcode was originally designed to render the OpenAPI spec inline using the Redoc component. A later change (c3f0681) replaced the Redoc<script>tag with a<meta http-equiv="refresh">, causing the page to immediately redirect to the Swagger editor instead, leaving the Redoc component output unreachable and producing an abrupt browser experience.This commit restores inline rendering by bringing the shortcode back in line with the Docsy v0.14.3 original it was copied from, substituting only the URL resolution block with the Polaris-specific
rawGithubPolarisUrlpartial.A separate "Open in Swagger Editor ↗" link is added for users who prefer the editor, and the ↗ suffix is removed from the sidebar link titles since the pages no longer redirect.
Checklist
CHANGELOG.md(if needed)site/content/in-dev/unreleased(if needed)