You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "adutra (via GitHub)" <gi...@apache.org> on 2026/09/02 22:46:25 UTC
[PR] Site: restore inline Redoc rendering for API spec pages [polaris]
adutra opened a new pull request, #5434:
URL: https://github.com/apache/polaris/pull/5434
The `redoc-polaris` shortcode was originally designed to render the OpenAPI spec inline using the Redoc component. A later change (c3f0681354c8e31f31de5ecf6a69ee68d680aa38) 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.
<!--
๐ Describe what changes you're proposing, especially breaking or user-facing changes.
๐ See https://github.com/apache/polaris/blob/main/CONTRIBUTING.md for more.
-->
## Checklist
- [ ] ๐ก๏ธ Don't disclose security issues! (contact security@apache.org)
- [ ] ๐ Clearly explained why the changes are needed, or linked related issues: Fixes #
- [ ] ๐งช Added/updated tests with good coverage, or manually tested (and explained how)
- [ ] ๐ก Added comments for complex logic
- [ ] ๐งพ Updated `CHANGELOG.md` (if needed)
- [ ] ๐ Updated documentation in `site/content/in-dev/unreleased` (if needed)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "orca-review-bot (via GitHub)" <gi...@apache.org>.
orca-review-bot commented on code in PR #5434:
URL: https://github.com/apache/polaris/pull/5434#discussion_r4392435415
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -1,19 +1,39 @@
{{/*
Apache Polaris custom redoc shortcode that takes just the file of the OpenAPI spec YAML and loads
-either the in-development version from the `main` branch or a released version from the corresponding
+either the in-development version from the local checkout or a released version from the corresponding
Git tag.
-This is a copy of the original Docsy redoc shortcode, except the part to calculate the URL is adopted
-for Polaris in-dev/releases docs.
+This is a copy of the Docsy redoc shortcode (v0.14.3), except the URL resolution block is replaced
+with a Polaris-specific partial that resolves the spec to the correct raw GitHub URL.
-Copied from Docsy shortcodes/redoc.html.
+Copied from Docsy:
+https://github.com/google/docsy/blob/v0.14.3/layouts/_shortcodes/redoc.html
*/}}
{{- $spec := .Get 0 -}}
{{- $otheroptions := .Get 1 -}}
{{- $url := partial "rawGithubPolarisUrl.html" (dict "page" . "path" (printf "spec/%s" $spec)) -}}
+{{- /*
+Publish the spec with the site, since the ASF CSP blocks fetching it from raw.githubusercontent.com
+in the browser. In-dev pages use the spec from the local checkout (`assets/polaris-spec` is a
+symlink to `spec/`), so the result always matches the commit being built. Released
+pages fetch the spec from the release tag. The build fails if the spec cannot be found.
+Spec URLs follow the pattern: https://polaris.apache.org/api-specs/{gitRef}/{spec}, e.g.
+https://polaris.apache.org/api-specs/apache-polaris-1.9.0/polaris-management-service.yml
+*/ -}}
+{{- $gitRef := partial "polarisGitRef.html" . -}}
+{{- $specResource := "" -}}
+{{- if $gitRef.isReleased -}}
+ {{- $specResource = resources.GetRemote $url -}}
Review Comment:
Every released page now fetches its spec from raw GitHub at build time, and any failure hits the `errorf` and kills the whole site publish. The paths all exist on current tags, so the risk is a flaky network, not a bad path. Before this PR the same failure just meant a broken redirect on one page. Are you fine with that tradeoff, or should we `warnf` and fall back to only the Swagger link?
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -83,11 +103,19 @@
<!--
Redoc element with link to your OpenAPI definition
-->
+<p><a href="https://editor-next.swagger.io/?url={{ $url | urlquery }}" target="_blank" rel="noopener">Open in Swagger Editor โ</a></p>
Review Comment:
For in-dev pages `$url` resolves to `refs/heads/main` (rawGithubPolarisUrl.html), but the inline view renders the local checkout. On a PR preview or a local build, the Swagger editor can show a different spec than the page. Is that OK, or should the link only show on released pages, or point at `$specUrl` as an absolute URL?
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra merged PR #5434:
URL: https://github.com/apache/polaris/pull/5434
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on code in PR #5434:
URL: https://github.com/apache/polaris/pull/5434#discussion_r4334531501
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -4,16 +4,29 @@
either the in-development version from the `main` branch or a released version from the corresponding
Git tag.
-This is a copy of the original Docsy redoc shortcode, except the part to calculate the URL is adopted
-for Polaris in-dev/releases docs.
+This is a copy of the Docsy redoc shortcode (v0.14.3), except the URL resolution block is replaced
+with a Polaris-specific partial that resolves the spec to the correct raw GitHub URL.
-Copied from Docsy shortcodes/redoc.html.
+Copied from Docsy:
+https://github.com/google/docsy/blob/v0.14.3/layouts/_shortcodes/redoc.html
*/}}
{{- $spec := .Get 0 -}}
{{- $otheroptions := .Get 1 -}}
{{- $url := partial "rawGithubPolarisUrl.html" (dict "page" . "path" (printf "spec/%s" $spec)) -}}
+{{- /*
+Fetch the spec at build time and publish it with the site, since the ASF CSP blocks fetching
+it from raw.githubusercontent.com in the browser. Fail the build if it cannot be fetched.
+Spec URLs follow the pattern: https://polaris.apache.org/api-specs/{gitRef}/{spec}, e.g.
+https://polaris.apache.org/api-specs/apache-polaris-1.9.0/polaris-management-service.yml
+*/ -}}
+{{- $gitRef := partial "polarisGitRef.html" . -}}
+{{- $remoteSpec := resources.GetRemote $url -}}
Review Comment:
Thanks for moving the spec fetch to build time, that solves the CSP problem for the browser.
One concern about where the spec is fetched from: for in-dev pages, `rawGithubPolarisUrl.html` resolves to `refs/heads/main`, which is a moving ref. As a result:
- PR builds always render main's spec, so changes to `spec/*.yaml` in a PR are never validated by the Site Generation job.
- The publishing build checks out main and then fetches `refs/heads/main` separately, so a push in between can produce a spec that doesn't match the published commit.
- Local builds keep `site/build/hugo-cache` across runs, and I think Hugo's getresource cache doesn't expire by default, so a local preview could keep showing an old main spec.
Would it make sense to distinguish the two cases?
- In-dev: use the spec from the local checkout, e.g. via symlinks like the existing ones in `site/content/` and `site/static/schemas/` (say `site/assets/polaris-spec/*.yml` -> `../../../spec/...`) and `resources.Get`. No network needed, and the result always matches the commit/working tree being built.
- Releases: keep fetching from the release tag, as now.
Pinning the raw URL to the commit SHA would fix the publishing case, but not local builds (an unpushed HEAD would 404 and fail the build).
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -83,11 +96,17 @@
<!--
Redoc element with link to your OpenAPI definition
-->
+<p><a href="https://editor-next.swagger.io/?url={{ $url | urlquery }}" target="_blank" rel="noopener">Open in Swagger Editor โ</a></p>
<div id="redoc-container">
-<redoc spec-url='{{ $url }}' hide-hostname="true" suppress-warnings="true" lazy-rendering native-scrollbars scroll-y-offset=".js-navbar-scroll" {{ $otheroptions }}></redoc>
+<redoc spec-url='{{ $specUrl }}' hide-hostname="true" suppress-warnings="true" lazy-rendering native-scrollbars scroll-y-offset=".js-navbar-scroll" {{ $otheroptions }}></redoc>
</div>
<!--
-Link to Redoc JavaScript on CDN for rendering standalone element
+Redoc JavaScript pinned and served locally to comply with ASF CSP policy
-->
-
-<meta http-equiv="refresh" content="0; url=http://editor-next.swagger.io/?url={{ $url }}" />
+{{- $redocUrl := "https://cdn.jsdelivr.net/npm/redoc@2.5.4/bundles/redoc.standalone.js" -}}
+{{ with resources.GetRemote $redocUrl }}
Review Comment:
I see this follows the jQuery/Lunr pattern in `head.html`.
Here, though, a missing script means an empty API page.
As far as I know, `resources.GetRemote` returns `nil` on a 404 instead of failing, so the `<script>` tag would be dropped without anyone noticing.
Could this fail the build the same way the spec fetch does?
Something like this maybe?
```
{{- $redoc := resources.GetRemote $redocUrl -}}
{{- if not $redoc -}}
{{- errorf "Cannot fetch Redoc bundle %s" $redocUrl -}}
{{- end -}}
<script
src="{{ $redoc.RelPermalink }}"
integrity="sha512-..."
crossorigin="anonymous"></script>
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on PR #5434:
URL: https://github.com/apache/polaris/pull/5434#issuecomment-6124636193
@snazy and @flyingImer ping
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #5434:
URL: https://github.com/apache/polaris/pull/5434#discussion_r4404218990
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -83,11 +103,19 @@
<!--
Redoc element with link to your OpenAPI definition
-->
+<p><a href="https://editor-next.swagger.io/?url={{ $url | urlquery }}" target="_blank" rel="noopener">Open in Swagger Editor โ</a></p>
Review Comment:
Kept as is: the editor needs a publicly reachable URL, so main is the best stand-in for in-dev. It can differ from the page only in PR previews and local builds.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on PR #5434:
URL: https://github.com/apache/polaris/pull/5434#issuecomment-5890495060
@snazy and @flyingImer are you OK with the latest changes?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on code in PR #5434:
URL: https://github.com/apache/polaris/pull/5434#discussion_r4404208850
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -1,19 +1,39 @@
{{/*
Apache Polaris custom redoc shortcode that takes just the file of the OpenAPI spec YAML and loads
-either the in-development version from the `main` branch or a released version from the corresponding
+either the in-development version from the local checkout or a released version from the corresponding
Git tag.
-This is a copy of the original Docsy redoc shortcode, except the part to calculate the URL is adopted
-for Polaris in-dev/releases docs.
+This is a copy of the Docsy redoc shortcode (v0.14.3), except the URL resolution block is replaced
+with a Polaris-specific partial that resolves the spec to the correct raw GitHub URL.
-Copied from Docsy shortcodes/redoc.html.
+Copied from Docsy:
+https://github.com/google/docsy/blob/v0.14.3/layouts/_shortcodes/redoc.html
*/}}
{{- $spec := .Get 0 -}}
{{- $otheroptions := .Get 1 -}}
{{- $url := partial "rawGithubPolarisUrl.html" (dict "page" . "path" (printf "spec/%s" $spec)) -}}
+{{- /*
+Publish the spec with the site, since the ASF CSP blocks fetching it from raw.githubusercontent.com
+in the browser. In-dev pages use the spec from the local checkout (`assets/polaris-spec` is a
+symlink to `spec/`), so the result always matches the commit being built. Released
+pages fetch the spec from the release tag. The build fails if the spec cannot be found.
+Spec URLs follow the pattern: https://polaris.apache.org/api-specs/{gitRef}/{spec}, e.g.
+https://polaris.apache.org/api-specs/apache-polaris-1.9.0/polaris-management-service.yml
+*/ -}}
+{{- $gitRef := partial "polarisGitRef.html" . -}}
+{{- $specResource := "" -}}
+{{- if $gitRef.isReleased -}}
+ {{- $specResource = resources.GetRemote $url -}}
Review Comment:
We want the build to fail.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #5434:
URL: https://github.com/apache/polaris/pull/5434#discussion_r3919379729
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -83,11 +84,11 @@
<!--
Redoc element with link to your OpenAPI definition
-->
+<p><a href="http://editor-next.swagger.io/?url={{ $url }}" target="_blank" rel="noopener">Open in Swagger Editor โ</a></p>
Review Comment:
The Swagger Editor link uses plain HTTP and passes the raw spec URL unescaped. This can cause mixed-content issues on HTTPS docs sites, and the `url=` query should be URL-encoded to handle any special characters safely.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5434:
URL: https://github.com/apache/polaris/pull/5434#discussion_r3961220542
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -83,11 +84,11 @@
<!--
Redoc element with link to your OpenAPI definition
-->
+<p><a href="https://editor-next.swagger.io/?url={{ $url | urlquery }}" target="_blank" rel="noopener">Open in Swagger Editor โ</a></p>
<div id="redoc-container">
<redoc spec-url='{{ $url }}' hide-hostname="true" suppress-warnings="true" lazy-rendering native-scrollbars scroll-y-offset=".js-navbar-scroll" {{ $otheroptions }}></redoc>
</div>
<!--
Link to Redoc JavaScript on CDN for rendering standalone element
-->
-
-<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>
Review 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?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on code in PR #5434:
URL: https://github.com/apache/polaris/pull/5434#discussion_r3948328469
##########
site/layouts/shortcodes/redoc-polaris.html:
##########
@@ -83,11 +84,11 @@
<!--
Redoc element with link to your OpenAPI definition
-->
+<p><a href="https://editor-next.swagger.io/?url={{ $url | urlquery }}" target="_blank" rel="noopener">Open in Swagger Editor โ</a></p>
<div id="redoc-container">
<redoc spec-url='{{ $url }}' hide-hostname="true" suppress-warnings="true" lazy-rendering native-scrollbars scroll-y-offset=".js-navbar-scroll" {{ $otheroptions }}></redoc>
</div>
<!--
Link to Redoc JavaScript on CDN for rendering standalone element
-->
-
-<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>
Review Comment:
(Re)adding Redoc rendering for API specs is nice!
This line however is [concerning](https://infra.apache.org/csp.html).
The current site build already fetches pinned jQuery and Lunr scripts, adding/using a pinned Redoc JS would resolve the concern.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "adutra (via GitHub)" <gi...@apache.org>.
adutra commented on PR #5434:
URL: https://github.com/apache/polaris/pull/5434#issuecomment-6268736574
> 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.
Apologies, I completely missed that, and it makes total sense. I just implemented your suggestion, PTAL again.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Site: restore inline Redoc rendering for API spec pages [polaris]
Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on PR #5434:
URL: https://github.com/apache/polaris/pull/5434#issuecomment-6134046385
> @snazy and @flyingImer ping
Thanks for the reminder, the pinned, site-hosted Redoc bundle addresses the script issue. I'd still hold approval on the YAML part of the [existing thread](https://github.com/apache/polaris/pull/5434#discussion_r3961220542). IIUC, Redoc still loads the spec from raw.githubusercontent.com, and today's production CSP blocks that fetch because connect-src falls back to default-src. Could we fetch the version-resolved YAML during the Hugo build too and pass its local URL to Redoc? We'd need to verify that both API pages render the correct specs under the production CSP. The green Site Generation job doesn't exercise that browser loading path.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org