Milestone 2: OpenAPI code generation lift (oapi-codegen + openapi-typescript)

.github/workflows/api.yaml

@@ -5,10 +5,12 @@ on:
     branches: [main]
     paths:
       - 'api/**'
+      - 'docs/openapi/**'
       - '.github/workflows/api.yaml'
   pull_request:
     paths:
       - 'api/**'
+      - 'docs/openapi/**'
       - '.github/workflows/api.yaml'
   workflow_dispatch:
 
@@ -20,7 +22,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  GO_VERSION: '1.25.4'
+  GO_VERSION: '1.26.3'
 
 jobs:
   build:
@@ -41,6 +43,15 @@ jobs:
       - name: Go module verify
         run: go mod download && go mod verify
 
+      - name: Verify generated code is up to date
+        run: |
+          go generate ./internal/api
+          if ! git diff --quiet -- internal/api; then
+            echo "::error::generated code is out of date — run 'go generate ./internal/api' from api/ and commit"
+            git --no-pager diff -- internal/api
+            exit 1
+          fi
+
       - name: Vet
         run: go vet ./...
 

.github/workflows/docs.yaml

@@ -28,7 +28,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  NODE_VERSION: '22'
+  NODE_VERSION: '24'
   PNPM_VERSION: '9'
 
 jobs:

.github/workflows/web.yaml

@@ -5,13 +5,15 @@ on:
     branches: [main]
     paths:
       - 'web/**'
+      - 'docs/openapi/**'
       - 'pnpm-workspace.yaml'
       - 'pnpm-lock.yaml'
       - 'package.json'
       - '.github/workflows/web.yaml'
   pull_request:
     paths:
       - 'web/**'
+      - 'docs/openapi/**'
       - 'pnpm-workspace.yaml'
       - 'pnpm-lock.yaml'
       - 'package.json'
@@ -26,7 +28,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  NODE_VERSION: '22'
+  NODE_VERSION: '24'
   PNPM_VERSION: '9'
 
 jobs:
@@ -49,6 +51,15 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Verify generated types are up to date
+        run: |
+          pnpm --filter @stig-manager-react/web gen:api
+          if ! git diff --quiet -- web/src/lib/api/schema.ts; then
+            echo "::error::generated types are out of date — run 'pnpm --filter web gen:api' and commit"
+            git --no-pager diff -- web/src/lib/api/schema.ts
+            exit 1
+          fi
+
       - name: Lint
         run: pnpm --filter @stig-manager-react/web lint
 

README.md

@@ -4,7 +4,7 @@ A modern re-implementation of
 [NUWCDIVNPT/stig-manager](https://github.com/NUWCDIVNPT/stig-manager):
 
 - **Frontend:** React 19 + Vite + TypeScript + [shadcn/ui](https://ui.shadcn.com).
-- **Backend:** Go 1.25 (`net/http` + `chi`), OpenAPI 3.0.1 v1 — byte-compatible with upstream.
+- **Backend:** Go 1.26 (`net/http` + `chi`), OpenAPI 3.0.1 v1 — byte-compatible with upstream.
 - **Database:** PostgreSQL 18 (via pgx v5).
 - **Auth:** OIDC / OAuth 2.0 PKCE (Keycloak / Okta / Azure Entra ID).
 - **Docs:** [Astro Starlight](https://starlight.astro.build/) (this repo's `docs/`).
@@ -24,8 +24,8 @@ A modern re-implementation of
 
 ## Prerequisites
 
-- **Node.js 22** and **pnpm 9** (via [Corepack](https://nodejs.org/api/corepack.html)).
-- **Go 1.25** for the API.
+- **Node.js 24** and **pnpm 9** (via [Corepack](https://nodejs.org/api/corepack.html)).
+- **Go 1.26** for the API.
 - **Docker / Docker Compose** for the integrated dev stack.
 
 ## Quick start (everything via compose)

api/Dockerfile → api/Containerfile

@@ -1,5 +1,15 @@
+# OCI image build for the STIG Manager API.
+#
+# This Containerfile follows the Open Container Initiative image-spec
+# (https://github.com/opencontainers/image-spec). The syntax is the same
+# format Docker uses; Podman, Buildah, and BuildKit also build it natively.
+#
+# Build with either:
+#   podman build -t stigman-api -f api/Containerfile api/
+#   docker build -t stigman-api -f api/Containerfile api/
+
 # syntax=docker/dockerfile:1.7
-FROM golang:1.23-alpine AS build
+FROM docker.io/library/golang:1.26.3-alpine AS build
 WORKDIR /src
 
 COPY go.mod go.sum ./

api/README.md

@@ -2,12 +2,13 @@
 
 Go HTTP API server for [stig-manager-react](https://github.com/Exonical/stig-manager-react).
 
-- Go 1.23, [`chi`](https://github.com/go-chi/chi) router, structured logging
+- Go 1.26, [`chi`](https://github.com/go-chi/chi) router, structured logging
   via `log/slog`.
 - [`pgx`](https://github.com/jackc/pgx) v5 for Postgres 18.
-- OpenAPI v1 surface (currently stubbed: `/api/v1/op/appinfo`,
-  `/api/v1/op/appdata/tables`). Code-generated handlers from
-  `docs/openapi/stig-manager.yaml` arrive in Milestone 2.
+- OpenAPI v1 surface served at `/api/*`, generated from
+  `docs/openapi/stig-manager.yaml` by [`oapi-codegen`](https://github.com/oapi-codegen/oapi-codegen).
+  All 150+ operations are wired up; unimplemented endpoints return 501
+  until real handlers land in later milestones.
 
 ## Local development
 
@@ -23,7 +24,7 @@ Smoke test:
 
 ```bash
 curl -s http://localhost:54001/health
-curl -s http://localhost:54001/api/v1/op/appinfo | jq
+curl -s http://localhost:54001/api/op/appinfo | jq
 ```
 
 ## Test, lint, build
@@ -40,12 +41,18 @@ go build ./...
 api/
 ├── cmd/stigman/main.go        program entrypoint
 ├── internal/
+│   ├── api/                   oapi-codegen generated types + chi router
+│   │   ├── gen.go             go:generate directives
+│   │   ├── server-config.yaml oapi-codegen config (chi server)
+│   │   ├── types-config.yaml  oapi-codegen config (models)
+│   │   ├── server.gen.go      generated chi router
+│   │   └── types.gen.go       generated request/response types
 │   ├── config/                env-based configuration
-│   ├── handlers/              HTTP handlers (scaffold)
-│   ├── server/                router wiring
+│   ├── handlers/              top-level handlers (e.g. /health)
+│   ├── server/                router wiring + APIServer overrides
 │   └── store/                 Postgres data layer (scaffold)
 ├── go.mod
-└── Dockerfile                 multi-stage distroless build
+└── Containerfile              OCI multi-stage distroless build
 ```
 
 ## Environment

api/go.mod

@@ -1,17 +1,41 @@
 module github.com/Exonical/stig-manager-react/api
 
-go 1.25.0
+go 1.26.3
 
 require (
+	github.com/getkin/kin-openapi v0.135.0
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/go-chi/cors v1.2.2
 	github.com/jackc/pgx/v5 v5.9.2
+	github.com/oapi-codegen/runtime v1.4.0
 )
 
 require (
+	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
+	github.com/dprotaso/go-yit v0.0.0-20220510233725-9ba8df137936 // indirect
+	github.com/go-openapi/jsonpointer v0.22.4 // indirect
+	github.com/go-openapi/swag/jsonname v0.25.4 // indirect
+	github.com/google/uuid v1.6.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
-	golang.org/x/sync v0.17.0 // indirect
-	golang.org/x/text v0.29.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/mailru/easyjson v0.9.1 // indirect
+	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
+	github.com/oapi-codegen/oapi-codegen/v2 v2.7.0 // indirect
+	github.com/oasdiff/yaml v0.0.9 // indirect
+	github.com/oasdiff/yaml3 v0.0.9 // indirect
+	github.com/perimeterx/marshmallow v1.1.5 // indirect
+	github.com/speakeasy-api/jsonpath v0.6.3 // indirect
+	github.com/speakeasy-api/openapi v1.19.2 // indirect
+	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect
+	github.com/woodsbury/decimal128 v1.4.0 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/mod v0.33.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
+	golang.org/x/tools v0.42.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
+
+tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen