chore(web): TS API client type generation (#3096)

* chore(web): initial setup for TS API client type generation

* chore: almost there

* chore: all tests are green

* chore: close to done

* chore: update the docs

* chore: comment

* chore: simplify fetch calls

* chore: more cleanup and feedback

* chore: feedback

* chore: eslint

Author: JGAntunes

.github/workflows/ci.yaml

@@ -75,12 +75,9 @@ jobs:
       - name: Install dependencies
         run: |
           npm install
-      - name: Run web lint
+      - name: Run web tests (types check, lint, and unit tests)
         run: |
-          npm run lint
-      - name: Run web unit tests
-        run: |
-          npm run test:unit
+          npm run test
       - name: Build web
         run: |
           npm run build

Makefile

@@ -342,6 +342,14 @@ scan:
 		--ignore-unfixed \
 		./
 
+.PHONY: api-types
+api-types:
+	@echo "Generating OpenAPI documentation..."
+	$(MAKE) -C api swagger
+	@echo "Generating TypeScript types from OpenAPI spec..."
+	cd web && npm run types:api:generate
+	@echo "API types generated successfully!"
+
 .PHONY: list-distros
 list-distros:
 	@$(MAKE) -C dev/distros list

README.md

@@ -382,6 +382,22 @@ The build system checks for overrides in this order:
 
 The system automatically generates a KOTS version string based on your override, ensuring proper versioning for development builds on rebuilds.
 
+## API Type Generation (V3 Manager Experience Only)
+
+The V3 manager experience uses OpenAPI/Swagger to generate TypeScript types for the web frontend. When you make changes to API endpoints or types in the `api/` directory for the V3 installer, you need to regenerate the types:
+
+```bash
+make api-types
+```
+
+This command:
+1. Generates OpenAPI documentation from Go code annotations (`api/docs/swagger.yaml`)
+2. Generates TypeScript types from the OpenAPI spec (`web/src/types/api.ts`)
+
+The types are automatically generated before building the web frontend (`npm run build` runs `types:api:generate` as a pre-build step), but you should run `make api-types` manually when developing API changes to ensure the frontend types stay in sync.
+
+**Note:** This is only relevant when working on the V3 manager experience (the new installer UI). The V2 experience uses KOTS admin console and does not use these generated types.
+
 ## Dependency Versions
 
 The [versions.mk](versions.mk) file serves as the single source of truth for all external dependency versions.

api/Makefile

@@ -6,7 +6,7 @@ include ../versions.mk
 .PHONY: swagger
 swagger: swag
 	swag fmt -g api.go
-	swag init --parseDependency --v3.1 -g api.go
+	swag init --parseDependency --requiredByDefault --v3.1 -g api.go
 
 .PHONY: swag
 swag: