diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b0f273..99f0e37 100644 --- 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 -[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 index d573454..9b20efe 100644 --- 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 + **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 index f2de9e8..4a38867 100644 --- 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): + +- + 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 new file mode 100644 index 0000000..fa0ebe0 --- /dev/null +++ b/index.html @@ -0,0 +1,45 @@ + + + + + + + HyperFleet Template API — Swagger UI + + + +
+ + + + + diff --git a/main.tsp b/main.tsp index 127953f..0c98c3a 100644 --- 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 index 1ca87fe..da2429a 100644 --- 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 index c07e52c..5b99740 100644 --- 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: