TypeSpec migration milestone 1: Generate Swagger from TypeSpec by kimorris27 · Pull Request #4791 · Azure/ARO-RP

kimorris27 · 2026-04-23T20:05:07Z

Which issue this PR addresses:

First in a series of PRs for https://redhat.atlassian.net/browse/ARO-23228

What this PR does / why we need it:

This PR sets us up to generate the Swagger API specifications for the v20250725 API and any future API versions from TypeSpec rather than from the Go structs in pkg/api. It also relocates the spec for the v20250725 API from swagger to api.

Many of the files changed in this PR are generated or copied from the upstream azure-rest-api-specs repo. You'll have the best review experience going through the commits, where I explain in detail what each one does.

Test plan for issue:

Had to run new make targets locally to generate Swagger and examples; also ran make generate-swagger-legacy to make sure it still worked

Is there any documentation that needs to be updated for this PR?

Doc changes are included in this PR

How do you know this will function as expected in production?

API spec for v20250725 has not functionally changed; it's just generated differently.

See Azure/azure-rest-api-specs#41462 if you're curious about any diffs between the pre-TypeSpec and post-TypeSpec versions of the v20250725 API spec.

Copilot

Pull request overview

Migrates Swagger generation for the 2025-07-25 (and future) API versions from Go-struct-derived Swagger to TypeSpec-derived Swagger, relocating the new spec artifacts under api/ and adding tooling/docs to support the new pipeline.

Changes:

Adds TypeSpec source-of-truth for Microsoft.RedHatOpenShift/OpenShiftClusters and tooling to compile it to Swagger and generate examples.
Updates make generate flow and introduces new targets/scripts for TypeSpec-based Swagger generation while keeping a legacy path for older API versions.
Moves/remodels API example files for 2025-07-25 (removing legacy swagger examples and adding generated examples under api/.../OpenShiftClusters/examples), and vendors common-types into api/common-types.

Reviewed changes

Copilot reviewed 79 out of 83 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/PlatformWorkloadIdentityRoleSets_List.json	Removes legacy swagger example (moved to TypeSpec-generated examples under `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/PlatformWorkloadIdentityRoleSet_Get.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/Operations_List.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftVersions_List.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftVersions_Get.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_Update.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_ListCredentials.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_ListByResourceGroup.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_ListAdminCredentials.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_List.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_Get.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_Delete.json	Removes legacy swagger example (moved to `api/`).
swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_CreateOrUpdate.json	Removes legacy swagger example (moved to `api/`).
hack/swagger-legacy/swagger.go	Adds wrapper binary for legacy Go-struct-based swagger generation.
hack/ci-utils/isClean.sh	Updates cleanliness check to ignore TypeSpec-generated example churn under `api/.../examples`.
hack/apiclients/generate-swagger-checksum.sh	Removes old checksum helper (replaced by `hack/api/generate-swagger-checksum.sh`).
hack/api/swagger-from-typespec.sh	Adds TypeSpec formatting/compilation + example generation script.
hack/api/generate-swagger-checksum.sh	Adds checksum generation that can look in swagger vs api locations.
hack/api/build-dev-api-clients.sh	Adds client generation script (Go track1 + Python track2) for selected API versions.
docs/api-versions.md	Documents the new TypeSpec-based swagger generation workflow and legacy workflow.
docs/agent-guides/api-type-system.md	Updates “Swagger Generation” documentation to include the TypeSpec path and renames legacy generator references.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/tspconfig.yaml	Adds TypeSpec compiler/emitter config for Swagger emission + SDK emitters.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/suppressions.yaml	Adds TypeSpec migration suppressions for brownfield/legacy specs.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.md	Adds AutoRest config for the new spec layout under `api/`.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.go.md	Adds Go SDK generation guidance/config.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.java.md	Adds Java SDK generation guidance/config.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.python.md	Adds Python SDK generation guidance/config.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.typescript.md	Adds TypeScript SDK generation guidance/config.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/models.tsp	Introduces TypeSpec models for the OpenShiftClusters RP API surface.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/main.tsp	Defines service namespace, versions, and top-level interface wiring for TypeSpec.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/client.tsp	Adds client-generator naming overrides for multi-language SDK compatibility.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/back-compatible.tsp	Adds legacy flattening and naming overrides for backward compatibility.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/OpenShiftCluster.tsp	TypeSpec resource + operations definition for OpenShiftClusters.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/OpenShiftVersion.tsp	TypeSpec resource + operations definition for OpenShiftVersions.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/PlatformWorkloadIdentityRoleSet.tsp	TypeSpec resource + operations definition for PlatformWorkloadIdentityRoleSets.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/PlatformWorkloadIdentityRoleSets_List_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/PlatformWorkloadIdentityRoleSet_Get_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/Operations_List_MinimumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/Operations_List_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftVersions_List_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftVersions_Get_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Update_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_List_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListCredentials_MinimumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListCredentials_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListByResourceGroup_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListAdminCredentials_MinimumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListAdminCredentials_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Get_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Delete_MinimumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Delete_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_CreateOrUpdate_MaximumSet_Gen.json	Adds generated example under `api/` for the new pipeline.
api/package.json	Adds Node/TypeSpec/oav dependencies and scripts for format/compile/examples.
api/common-types/rfcs/rfc7517.json	Vendors RFC common type definitions into `api/common-types`.
api/common-types/resource-management/v6/privatelinks.json	Vendors ARM common types v6 (private links).
api/common-types/resource-management/v6/managedidentity.json	Vendors ARM common types v6 (managed identity).
api/common-types/resource-management/v5/privatelinks.json	Vendors ARM common types v5.
api/common-types/resource-management/v5/networksecurityperimeter.json	Vendors ARM common types v5 (NSP).
api/common-types/resource-management/v5/mobo.json	Vendors ARM common types v5 (MOBO).
api/common-types/resource-management/v5/managedidentitywithdelegation.json	Vendors ARM common types v5 (delegation).
api/common-types/resource-management/v5/managedidentity.json	Vendors ARM common types v5 (managed identity).
api/common-types/resource-management/v5/customermanagedkeys.json	Vendors ARM common types v5 (CMK).
api/common-types/resource-management/v4/privatelinks.json	Vendors ARM common types v4.
api/common-types/resource-management/v4/managedidentitywithdelegation.json	Vendors ARM common types v4 (delegation).
api/common-types/resource-management/v4/managedidentity.json	Vendors ARM common types v4 (managed identity).
api/common-types/resource-management/v4/customermanagedkeys.json	Vendors ARM common types v4 (CMK).
api/common-types/resource-management/v3/privatelinks.json	Vendors ARM common types v3.
api/common-types/resource-management/v3/managedidentity.json	Vendors ARM common types v3 (managed identity).
api/common-types/resource-management/v2/privatelinks.json	Vendors ARM common types v2.
api/common-types/resource-management/v1/types.json	Vendors ARM common types v1 core types.
api/common-types/resource-management/v1/privatelinks.json	Vendors ARM common types v1 (private links).
api/common-types/data-plane/v1/types.json	Vendors data-plane common types.
Makefile	Introduces TypeSpec image/targets and updates `generate` + swagger checksum flow.
Dockerfile.typespec	Adds container image for TypeSpec toolchain execution.
.sha256sum	Updates spec checksum list to include the relocated 2025-07-25 swagger.
.gitignore	Ignores `api/node_modules` created by the new toolchain.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…RO-HCP Modelling `api` directory structure after ARO-HCP's

- `api/package.json` came from ARO-HCP; I removed Autorest - Ran `npm install` on my Mac to initialize `api/package-lock.json` - Created `Dockerfile.typespec` by copying `Dockerfile.autorest` and tweaking Note that I considered combining the Autorest and TypeSpec stuff into a unified "api tooling" image, but I ended up in dependency hell trying to get the Autorest implementation of `make client` working and so decided to use separate images (we theoretically don't need Autorest anymore anyway)

…rate-swagger` as `make generate-swagger-legacy` We probably don't need the old one anymore, but preserving it on the off chance that we do; it doesn't hurt anything

…able API, the only one we're generating from TypeSpec so far Motivation to use `api` as the source of truth for the current API version and newer ones is that it makes it easier to commit to upstream since the directory structures match; I think this outweighs the minor confusion/inconvenience of having two sets of Swagger API specs in two different places Other note: the new `make` target generates the examples with `oav` (referenced in ARO-HCP docs and used for their examples), and the examples seem to have changed between Autorest and `oav`; so these new examples are technically different from what's currently present in azure-rest-api-specs for this API version, but I say we don't worry about this until/unless it becomes a problem

…pi` directory along with a few other tweaks... - `hack/swagger` -> `hack/swagger-legacy` - Got rid of `hack/apiclients` and gathered a few things all related to API/client tooling into `hack/api`

… the fact that TypeSpec complains about conflicts with examples if you don't delete them before generating the Swagger This means that anyone who runs `make generate` will have to understand not commit the changed examples; I know this is a little annoying, but I think it's important to include the TypeSpec -> Swagger generation in `make generate` and the corresponding CI check (`git add *` is not a great practice anyway IMO)

- Typo in TypeSpec Dockerfile entrypoint - A little bit of a hack to ensure `node_modules` is initialized properly for running npm scripts in the container rather than on the host - Encapsulate `oav generate-examples` in an npm script

…typespec` Didn't think about how CI would be affected by containerizing TypeSpec stuff Note that `tsp format` output changed between containerized and non-containerized version for now; just pushing this to see how the CI generate check reacts for now

Copilot

Pull request overview

Copilot reviewed 78 out of 82 changed files in this pull request and generated 8 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

kimorris27 self-assigned this Apr 23, 2026

Copilot AI review requested due to automatic review settings April 23, 2026 20:05

kimorris27 added the chainsaw Pull requests or issues owned by Team Chainsaw label Apr 23, 2026

kimorris27 requested review from alcasim, bennerv, cadenmarchese, hawkowl, hlipsig, jharrington22, kevinobriendotca, mociarain, mrWinston, rogbas, sankur-codes, tiguelu, tsatam, tuxerrante, ventifus, wanghaoran1988 and yjst2012 as code owners April 23, 2026 20:05

Copilot started reviewing on behalf of kimorris27 April 23, 2026 20:06 View session

Copilot AI reviewed Apr 23, 2026

View reviewed changes

Comment thread docs/agent-guides/api-type-system.md Outdated

Comment thread docs/api-versions.md Outdated

Comment thread hack/api/generate-swagger-checksum.sh

Comment thread .sha256sum Outdated

Comment thread hack/ci-utils/isClean.sh

Comment thread Makefile Outdated

kimorris27 added 8 commits April 24, 2026 09:54

Copy TypeSpec files from azure-rest-api-specs and common-types from A…

01bbf87

…RO-HCP Modelling `api` directory structure after ARO-HCP's

Add make generate-swagger-typespec and preserve previous `make gene…

9fc7773

…rate-swagger` as `make generate-swagger-legacy` We probably don't need the old one anymore, but preserving it on the off chance that we do; it doesn't hurt anything

Update make generate to handle checksums for API versions in new `a…

67a88e2

…pi` directory along with a few other tweaks... - `hack/swagger` -> `hack/swagger-legacy` - Got rid of `hack/apiclients` and gathered a few things all related to API/client tooling into `hack/api`

Small fixes

f34b93e

- Typo in TypeSpec Dockerfile entrypoint - A little bit of a hack to ensure `node_modules` is initialized properly for running npm scripts in the container rather than on the host - Encapsulate `oav generate-examples` in an npm script

Update AI agent docs and add a human doc

e62ba34

kimorris27 force-pushed the kimorris27/ARO-23228-typespec-migration branch from 642b752 to 482420a Compare April 24, 2026 15:40

Case sensitivity fix

ea9cc10

Copilot AI review requested due to automatic review settings April 24, 2026 15:47

Copilot started reviewing on behalf of kimorris27 April 24, 2026 15:48 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

kimorris27 added 2 commits April 24, 2026 14:04

Appease yaml linter

d9ecf24

Various small fixes recommended by Copilot

f827a6b

kimorris27 added the work-in-progress label Apr 24, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TypeSpec migration milestone 1: Generate Swagger from TypeSpec#4791

TypeSpec migration milestone 1: Generate Swagger from TypeSpec#4791
kimorris27 wants to merge 12 commits intomasterfrom
kimorris27/ARO-23228-typespec-migration

kimorris27 commented Apr 23, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kimorris27 commented Apr 23, 2026

Which issue this PR addresses:

What this PR does / why we need it:

Test plan for issue:

Is there any documentation that needs to be updated for this PR?

How do you know this will function as expected in production?

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants