docs(platform): publish versioned interactive API reference (Swagger UI)#144
Merged
Conversation
![kodiak-appscode[bot]](https://avatars.githubusercontent.com/in/92481?s=60&v=4){kind=small}
|
Visit the preview URL for this PR (updated for commit e259f00): https://kubedb-v2-hugo--pr144-api-html-interactive-jepcjslc.web.app (expires Tue, 21 Jul 2026 10:01:37 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 Sign: 0f29ae8ae0bd54a99bf2b223b6833be47acd5943 |
Move the generated api.html into a leaf bundle under docs/platform/api/reference/ so the aggregator copies it into each versioned docs tree. A tiny index.md stub routes it through a raw-passthrough layout (type: swagger) that serves the self-contained Swagger UI verbatim at /docs/platform/<version>/api/reference/. Link it from the API README's OpenAPI paragraph (not the sidebar). Requires the companion layouts/swagger/single.html in the website repo. Signed-off-by: Tamal Saha <tamal@appscode.com>
tamalsaha
force-pushed
the
api-html-interactive-reference
branch
from
July 14, 2026 10:00
47a651c to
e259f00
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Publishes the generated
api.html(self-contained Swagger UI, spec inlined) as a per-version interactive API reference.api.html→ moved into a leaf bundle atdocs/platform/api/reference/api.html, so the aggregator copies it into each versioned docs tree.docs/platform/api/reference/index.md→ tiny stub (type: swagger) that routes the page through a raw-passthrough layout.docs/platform/api/README.md→ updates the existing OpenAPI paragraph to link the published interactive viewer (replacing the stale "available at the repository root" note). Not added to the left sidebar.Result — each release serves the exact standalone Swagger UI at:
Why a leaf bundle + passthrough layout
.htmlis a Hugo renderable content type: dropped intocontent/it renders as a wrapped page at the wrong URL; as a plain resource Hugo won't give it a permalink to publish. Making it a resource of a leaf bundle and emitting.Contentfrom a no-baseoflayout serves it byte-for-byte, while keepingapi.htmlpristine (no front matter injected) so the generator can keep overwriting it.Companion (land first)
Requires the passthrough layout: kubedb/website#407.
Verification
Simulated the aggregator into
content/docs/platform/v2026.7.10/...and built with the realhugo-product-theme(Hugo 0.128.2): the page renders byte-identical (cmp) to sourceapi.html, no theme chrome.Note
api.htmlnow lives underdocs/, so the liche link check will see itshttps://unpkg.com/...CDN links. If CI flags them, add.*unpkg.com.*to the-xexclude list in.github/workflows/ci.yml.