Check that the API docs are up to date on CI (#1490)

Signed-off-by: lujunsan <[email protected]>

Author: lujunsan

.github/workflows/verify-docgen.yml

@@ -15,4 +15,6 @@ jobs:
       - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
         with:
           go-version-file: go.mod
+      - name: Install swag
+        run: go install github.com/swaggo/swag/v2/cmd/swag@latest
       - run: ./cmd/help/verify.sh

cmd/help/verify.sh

@@ -1,10 +1,18 @@
 #!/usr/bin/env bash
 set -e
 
-# Verify that generated Markdown docs are up-to-date.
+# Verify that generated CLI docs are up-to-date.
 tmpdir=$(mktemp -d)
 go run cmd/help/main.go --dir "$tmpdir"
 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/server"
+swag init -g pkg/api/server.go --v3.1 -o "$api_tmpdir/server"
+# Exclude README.md from diff as it's manually maintained
+diff -Naur --exclude="README.md" "$api_tmpdir/server" docs/server/
+
 echo "######################################################################################"
 echo "If diffs are found, please run: \`task docs\` to regenerate the docs."
 echo "######################################################################################"