Add upstream API types

.github/workflows/verify-docgen.yml

@@ -12,9 +12,14 @@ jobs:
 
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5
+      - name: Install Task
+        uses: arduino/setup-task@v2
+        with:
+          version: 3.44.1
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
       - uses: actions/setup-go@44694675825211faa026b3c33043df3e48a5fa00 # v6
         with:
           go-version-file: go.mod
       - name: Install swag
-        run: go install github.com/swaggo/swag/v2/cmd/swag@latest
+        run: task install-swagger
       - run: ./cmd/help/verify.sh

.swaggo

@@ -0,0 +1,6 @@
+// replace internal/api/v0.EnvVarDetail EnvVarDetail
+// replace internal/api/v0.ErrorResponse ErrorResponse
+// replace internal/api/v0.ListServersResponse ListServersResponse
+// replace internal/api/v0.RegistryInfoResponse RegistryInfoResponse
+// replace internal/api/v0.ServerDetailResponse ServerDetailResponse
+// replace internal/api/v0.ServerSummaryResponse ServerSummaryResponse

Taskfile.yml

@@ -1,17 +1,20 @@
 version: '3'
 
-# includes:
-#   registry-api:
-#     taskfile: ./cmd/thv-registry-api/Taskfile.yml
-#     flatten: true
-
 tasks:
   docs:
     desc: Regenerate the registry API documentation
+    vars:
+      SWAG_OUTPUT_DIR: '{{.SWAG_OUTPUT_DIR | default "docs/thv-registry-api"}}'
     cmds:
       - rm -rf docs/cli/*
       - go run cmd/help/main.go --dir docs/cli
-      - swag init -g cmd/thv-registry-api/docs.go --v3.1 -o docs/thv-registry-api
+      # NOTE: check out .swaggo file in the root of the project
+      # NOTE: We suppress the output to avoid "go/build" messages, it might
+      #       drop messages we care about.
+      - |
+        swag init -q -g cmd/thv-registry-api/docs.go \
+          --v3.1 --output {{.SWAG_OUTPUT_DIR}} \
+          --parseDependencyLevel 1 2>/dev/null
 
   install-swagger:
     desc: Install the swag tool for OpenAPI/Swagger generation

cmd/help/verify.sh

@@ -9,7 +9,7 @@ diff -Naur -I "^  date:" "$tmpdir" docs/cli/
 # Generate API docs in temp directory that mimics the final structure
 api_tmpdir=$(mktemp -d)
 mkdir -p "$api_tmpdir/docs/thv-registry-api"
-swag init -g cmd/thv-registry-api/docs.go --v3.1 -o "$api_tmpdir/docs/thv-registry-api"
+task docs SWAG_OUTPUT_DIR="$api_tmpdir/docs/thv-registry-api"
 # Exclude README.md from diff as it's manually maintained
 diff -Naur --exclude="README.md" "$api_tmpdir/docs/thv-registry-api" docs/thv-registry-api/