Publish MTA REST API reference to GitHub Pages - #1886
Draft
boyan-velinov wants to merge 1 commit into
Draft
Conversation
Replace the exhausted SwaggerHub-hosted API docs with a self-hosted
interactive reference on GitHub Pages, auto-published from source control.
A new workflow (publish-docs.yml) triggers on changes to the generated
API specs (mtarest.yaml, mtarest_v2.yaml) and writes per-version Swagger
UI pages plus the raw YAML into the gh-pages branch under /api/. The
existing landing page is left untouched via a scoped `git add`.
- Swagger UI (swagger-ui-dist 5.32.11) is fetched at publish time and
SHA-256 verified before vendoring; no CDN dependency, no committed blob.
- A version folder is keyed off info.version; content changes without a
version bump fail the build unless the commit carries [docs-republish].
- info.version is validated against a semver allowlist before it is used
as a path segment or interpolated into generated HTML.
- Page markup is kept in .github/pages-templates/ and rendered with
literal placeholder substitution, keeping the workflow readable.
- Double-link between the landing page and the docs: generated pages carry
a Home link back to the site root; the landing page's existing API link
goes live once /api/ is published.
Point the README at the new location:
https://cloudfoundry.github.io/multiapps-controller/api/
boyan-velinov
force-pushed
the
improve-api-docu
branch
from
July 31, 2026 19:30
28bad93 to
78b5029
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.
Replace the exhausted SwaggerHub-hosted API docs with a self-hosted interactive reference on GitHub Pages, auto-published from source control.
A new workflow (publish-docs.yml) triggers on changes to the generated API specs (mtarest.yaml, mtarest_v2.yaml) and writes per-version Swagger UI pages plus the raw YAML into the gh-pages branch under /api/. The existing landing page is left untouched via a scoped
git add.Point the README at the new location:
https://cloudfoundry.github.io/multiapps-controller/api/