openshift-hyperfleet · openshift-merge-bot · Jun 4, 2026 · Jun 2, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.21] - 2026-06-02
+
+### Added
+
+- Swagger UI (`index.html`) for browsing the Template OpenAPI contract on GitHub Pages (swagger-ui-dist 5.32.6)
+
 ## [1.0.20] - 2026-06-01
 
 ### Added
@@ -62,7 +68,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `hyperfleet` npm dependency for importing shared models and services from the core repository
 
 <!-- Links -->
-[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec-template/compare/v1.0.20...HEAD
+
+[Unreleased]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec-template/compare/v1.0.21...HEAD
+[1.0.21]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec-template/compare/v1.0.20...v1.0.21
 [1.0.20]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec-template/compare/v1.0.19...v1.0.20
 [1.0.19]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec-template/compare/v1.0.18...v1.0.19
 [1.0.18]: https://github.com/openshift-hyperfleet/hyperfleet-api-spec-template/compare/v1.0.17...v1.0.18

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -5,14 +5,19 @@ This repository generates the HyperFleet Template OpenAPI specification from Typ
 ## Quick Reference
 
 **Build commands:**
+
 ```bash
-npm run build            # Generate Template OpenAPI 3.0
-npm run build:swagger    # Generate Template OpenAPI 3.0 + Swagger 2.0
+npm run build            # Generate Template OpenAPI 3.0 + Swagger 2.0
 ./build-schema.sh        # Same as npm run build
-./build-schema.sh --swagger  # Same as npm run build:swagger
 ```
 
+**Swagger UI (GitHub Pages):**
+
+- `index.html` loads `schemas/template/openapi.yaml` via raw.githubusercontent.com (swagger-ui-dist 5.32.6 from jsDelivr)
+- Published at <https://openshift-hyperfleet.github.io/hyperfleet-api-spec-template/>
+
 **Validation workflow:**
+
 ```bash
 npm install                              # Install dependencies (includes hyperfleet package)
 ./build-schema.sh                        # Build Template OpenAPI 3.0
@@ -47,14 +52,14 @@ To use a local core checkout during development, use `npm link` or a local path:
 
 ### What Lives Here vs Core
 
-| Concern | Location |
-|---------|----------|
-| Cluster/nodepool/status/resource CRUD routes | Core repo (`hyperfleet` package) |
-| `TemplateClusterSpec` fields | `models/cluster/model.tsp` |
-| Template nodepool fields | `models/nodepool/model.tsp` |
-| Channels and versions models | `models/channel/`, `models/version/` |
-| Channels and versions service endpoints | `services/channels.tsp`, `services/versions.tsp` |
-| Generated output | `schemas/template/openapi.yaml` (committed) |
+| Concern                                      | Location                                         |
+| -------------------------------------------- | ------------------------------------------------ |
+| Cluster/nodepool/status/resource CRUD routes | Core repo (`hyperfleet` package)                 |
+| `TemplateClusterSpec` fields                 | `models/cluster/model.tsp`                       |
+| Template nodepool fields                     | `models/nodepool/model.tsp`                      |
+| Channels and versions models                 | `models/channel/`, `models/version/`             |
+| Channels and versions service endpoints      | `services/channels.tsp`, `services/versions.tsp` |
+| Generated output                             | `schemas/template/openapi.yaml` (committed)      |
 
 ### Public vs Internal APIs
 
@@ -65,6 +70,7 @@ The internal status and force-delete endpoints come from the core shared contrac
 ### TypeSpec Conventions
 
 **Imports first, namespace second:**
+
 ```typescript
 import "@typespec/http";
 import "hyperfleet/shared/models/common/model.tsp";
@@ -74,6 +80,7 @@ namespace HyperFleet;
 ```
 
 **Model naming:**
+
 - Template resources: `TemplateClusterSpec`, `ReleaseSpec`, `ChannelSpec`, `VersionSpec`
 - Lists: `ChannelList`, `VersionList`
 - Requests: `ChannelCreateRequest`, `ChannelPatchRequest`
@@ -94,11 +101,13 @@ services/
 ## Boundaries
 
 **DO NOT:**
+
 - Modify generated files in `schemas/` or `tsp-output-template/` directly
 - Add shared/core models here — they belong in the core repo's `shared/` directory
 - Commit `node_modules/` or build artifacts
 
 **DO:**
+
 - Run `./build-schema.sh` and commit `schemas/template/openapi.yaml` with your changes
 - Run `./build-schema.sh --swagger` and commit `schemas/template/swagger.yaml` when releasing
 - Keep TypeSpec files focused (one resource per service file)
@@ -139,6 +148,7 @@ Rebuild: `npm run build`
 ### Add a new Template-specific resource
 
 1. Create model:
+
 ```typescript
 // models/policy/model.tsp
 import "@typespec/http";
@@ -151,7 +161,8 @@ model PolicySpec {
 }
 ```
 
-2. Create service:
+1. Create service:
+
 ```typescript
 // services/policies.tsp
 import "@typespec/http";
@@ -167,22 +178,25 @@ interface Policies {
 }
 ```
 
-3. Import both in `main.tsp`:
+1. Import both in `main.tsp`:
+
 ```typescript
 import "./models/policy/model.tsp";
 import "./services/policies.tsp";
 ```
 
-4. Build: `npm run build`
+1. Build: `npm run build`
 
 ### Update the hyperfleet core dependency
 
 1. Edit `package.json`:
+
 ```json
 "hyperfleet": "github:openshift-hyperfleet/hyperfleet-api-spec#v1.0.19"
 ```
 
-2. Reinstall and rebuild:
+1. Reinstall and rebuild:
+
 ```bash
 npm install
 npm run build
@@ -213,11 +227,13 @@ Before submitting changes:
 ## Build System Details
 
 **The build-schema.sh script:**
+
 1. Runs `node_modules/.bin/tsp compile main.tsp --output-dir tsp-output-template`
 2. Moves output to `schemas/template/openapi.yaml`
 3. (Optional with `--swagger`) Converts to OpenAPI 2.0 via `api-spec-converter` → `schemas/template/swagger.yaml`
 
 **Output locations:**
+
 - TypeSpec temp: `tsp-output-template/schema/openapi.yaml` (auto-deleted)
 - Final: `schemas/template/openapi.yaml` and `schemas/template/swagger.yaml` (committed)
 
@@ -226,6 +242,7 @@ Before submitting changes:
 Releases are **fully automated** via GitHub Actions (`.github/workflows/release.yml`).
 
 On every push to `main`, the release workflow:
+
 1. Extracts the version from the `@info` decorator in `main.tsp`
 2. Skips if a tag for that version already exists
 3. Builds both schema formats (`openapi.yaml` and `swagger.yaml`)

diff --git a/README.md b/README.md
@@ -1,6 +1,11 @@
 # HyperFleet Template API Spec
 
 This repository is a template for creating the public API contract for HyperFleet for a cloud provider.
+
+Browse the generated contract in Swagger UI (GitHub Pages):
+
+- <https://openshift-hyperfleet.github.io/hyperfleet-api-spec-template/index.html>
+
 The public contract is different from the internal (core) one because: only contains generic API endpoints (`/resource`)
 
 The core contract provides shared schemas for statuses, errors, pagination, etc... that are published as an NPM module that this repository adds as a dependency.
@@ -15,6 +20,7 @@ Both will be created by executing the build script.
 
 ```
 hyperfleet-api-spec-template/
+├── index.html                # Swagger UI (GitHub Pages, swagger-ui-dist 5.32.6)
 ├── main.tsp                  # Main TypeSpec entry point
 ├── tspconfig.yaml            # TypeSpec compiler configuration
 ├── build-schema.sh           # Build script for OpenAPI generation

diff --git a/index.html b/index.html
@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta
+    name="description"
+    content="HyperFleet Template API — Swagger UI"
+  />
+  <title>HyperFleet Template API — Swagger UI</title>
+  <link
+    rel="stylesheet"
+    href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.6/swagger-ui.css"
+    integrity="sha384-9Q2fpS+xeS4ffJy6CagnwoUl+4ldAYhOs9pgZuEKxypVModhmZFzeMlvVsAjf7uT"
+    crossorigin="anonymous"
+  />
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script
+    src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.6/swagger-ui-bundle.js"
+    integrity="sha384-EYdOaiRwn44zNjrw+Tfs06qYz9BGQVo2f4/pLY5i7VorbjnZNhdplAbTBk8FXHUJ"
+    crossorigin="anonymous"
+  ></script>
+  <script
+    src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.32.6/swagger-ui-standalone-preset.js"
+    integrity="sha384-49fpFaVrAWI/qdgl9Vv5E/4NXxRUiJX5vGuLws1NUpTWGtEqzWEx8gHTw2UTehFK"
+    crossorigin="anonymous"
+  ></script>
+  <script>
+    window.onload = () => {
+      window.ui = SwaggerUIBundle({
+        url: 'https://raw.githubusercontent.com/openshift-hyperfleet/hyperfleet-api-spec-template/refs/heads/main/schemas/template/openapi.yaml',
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset,
+        ],
+        layout: 'StandaloneLayout',
+      });
+    };
+  </script>
+</body>
+</html>
diff --git a/main.tsp b/main.tsp
@@ -33,7 +33,7 @@ using OpenAPI;
  */
 @service(#{ title: "HyperFleet API" })
 @info(#{
-  version: "1.0.20",
+  version: "1.0.21",
   contact: #{
     name: "HyperFleet Team",
     url: "https://github.com/openshift-hyperfleet",

diff --git a/schemas/template/openapi.yaml b/schemas/template/openapi.yaml
@@ -1,7 +1,7 @@
 openapi: 3.0.0
 info:
   title: HyperFleet API
-  version: 1.0.20
+  version: 1.0.21
   contact:
     name: HyperFleet Team
     url: https://github.com/openshift-hyperfleet

diff --git a/schemas/template/swagger.yaml b/schemas/template/swagger.yaml
@@ -17,7 +17,7 @@ info:
     name: Apache 2.0
     url: 'https://www.apache.org/licenses/LICENSE-2.0'
   title: HyperFleet API
-  version: 1.0.20
+  version: 1.0.21
 host: hyperfleet.redhat.com
 basePath: /
 schemes: