Merge pull request #21 from git-pkgs/openapi-docs

Add generated OpenAPI docs support

Author: andrew

.github/workflows/swagger.yml

@@ -0,0 +1,36 @@
+name: Swagger
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  swagger:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version: '1.25'
+
+      - name: Install swag
+        run: go install github.com/swaggo/swag/cmd/swag@latest
+
+      - name: Generate swagger
+        run: go generate ./internal/server
+
+      - name: Verify no changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "Swagger docs are out of date. Run: go generate ./internal/server" >&2
+            git status --porcelain
+            exit 1
+          fi

README.md

@@ -65,6 +65,25 @@ go build -o proxy ./cmd/proxy
 
 The proxy is now running. Configure your package managers to use it.
 
+## OpenAPI (Swagger)
+
+This repo uses swaggo to generate an OpenAPI spec from annotated handlers.
+
+Generate the spec:
+
+```bash
+go install github.com/swaggo/swag/cmd/swag@latest
+go generate ./internal/server
+```
+
+Generated files are written to `docs/swagger/`.
+
+When the proxy is running, fetch the live spec from:
+
+- `http://localhost:8080/openapi.json`
+
+Or replace `http://localhost:8080` with your configured base URL. This link is also shown on the dashboard.
+
 ## Configuring Package Managers
 
 ### npm

cmd/proxy/main.go

@@ -1,5 +1,10 @@
 // Command proxy runs the git-pkgs package registry proxy server.
 //
+// @title git-pkgs proxy API
+// @version 0.1.0
+// @description HTTP API for package enrichment, vulnerability lookup, cache stats, and source browsing.
+// @BasePath /
+//
 // The proxy caches package artifacts from upstream registries (npm, cargo, etc.)
 // providing faster, more reliable access for development teams.
 //