Auto-generate OpenAPI spec from Go code using swaggo/swag

[danielbowne]

Problem

The OpenAPI spec (backend/openapi.yaml) is manually maintained and has drifted from the actual API multiple times:

• GET /datacalls/latest was missing
• DELETE /fismasystems/{fismasystemid} was missing
• FismaSystem decommission fields were missing from the schema

As we add more endpoints, this will only get worse.

Proposal

Adopt swaggo/swag to auto-generate openapi.yaml from Go handler annotations and struct definitions. This ensures the spec always matches the actual code.

Implementation

1. Add swag annotations to existing handlers

Add comment blocks above each controller function:

// @Summary Get the latest data call
// @Tags datacalls
// @Produce json
// @Success 200 {object} DataCall
// @Router /datacalls/latest [get]
func GetLatestDataCall(w http.ResponseWriter, r *http.Request) {

2. Add general API info annotation to main.go

// @title ZTMF API
// @version 1.0
// @description API for Zero Trust Maturity Framework
// @BasePath /api/v1

3. Makefile target

make generate-openapi    # runs swag init, outputs openapi.yaml

4. Git pre-commit hook

If any file in backend/cmd/api/internal/controller/ or backend/internal/model/ is staged, automatically run swag init and stage the updated spec. This way the spec can never drift.

5. CI validation (optional)

Add a CI step that runs swag init and fails if the generated spec differs from what's committed — catches cases where someone bypasses the hook.

Benefits

• Spec always matches code — no more drift
• Annotations double as inline docs for handlers
• Works with existing gorilla/mux + manual handlers — no rewrite needed
• Incremental adoption: annotate handlers one at a time

Scope

• Annotate all ~40 handler functions in backend/cmd/api/internal/controller/
• Add make generate-openapi target
• Add pre-commit hook for controller/model changes
• Remove manually maintained backend/openapi.yaml once migration is complete