feat: Publish an OpenAPI 3.1 document and a Scalar reference

Generated from swaggo v2 annotations, committed rather than built into the
image: the runtime stage is scratch and adding codegen puts the toolchain
in the build. CI regenerates and diffs, so an annotation edited without
regenerating fails the build — without that the annotations would drift
while still looking authoritative.

Scalar is vendored rather than loaded from a CDN, because air-gapped
self-hosted installs are supported and a reference page that fails closed
offline is a support ticket.

.gitea/workflows/server-deploy.yml

@@ -95,6 +95,24 @@ jobs:
                     docker login ${{ vars.DOCKER_HOST }} \
                       -u "${{ secrets.REGISTRY_USER }}" --password-stdin
 
+            - name: Set up Go
+              if: steps.changed.outputs.server == 'true'
+              uses: actions/setup-go@v5
+              with:
+                  go-version: "1.26"
+                  cache: true
+                  cache-dependency-path: server/go.sum
+
+            - name: Verify the OpenAPI document is current
+              if: steps.changed.outputs.server == 'true'
+              run: |
+                  go install github.com/swaggo/swag/v2/cmd/swag@v2.0.0-rc5
+                  cd server
+                  swag init --generalInfo cmd/main.go --dir ./,../shared \
+                    --output internal/api/docs --outputTypes json --v3.1
+                  mv -f internal/api/docs/swagger.json internal/api/docs/openapi.json
+                  git diff --exit-code internal/api/docs/openapi.json
+
             - name: Build and push server image
               if: steps.changed.outputs.server == 'true'
               run: |