feat: Add OpenAPI response types and top-level swag annotations

Named response types for handlers that were returning anonymous gin.H
literals, so a generated annotation and what the handler actually returns
cannot disagree. main.go carries the top-level swaggo info block (title,
description, security schemes for cookie, bearer token and ESO auth).

server/cmd/main.go

@@ -29,6 +29,24 @@ import (
 	"github.com/gin-gonic/gin"
 )
 
+//	@title						Vantage API
+//	@version					1.0
+//	@description				The Vantage control plane REST API. Authenticate with a browser session cookie, or with an API token created under Settings → API tokens.
+//	@BasePath					/api
+//
+//	@securityDefinitions.apikey	cookieAuth
+//	@in							cookie
+//	@name						km_session
+//
+//	@securityDefinitions.apikey	bearerAuth
+//	@in							header
+//	@name						Authorization
+//	@description				An API token, sent as "Bearer vt_…". Scoped and optionally expiring.
+//
+//	@securityDefinitions.apikey	esoAuth
+//	@in							header
+//	@name						Authorization
+//	@description				The External Secrets read token, rotated under Settings. It reaches /api/secrets/{group}/values and nothing else. It is a different credential from an API token, and the two must never be substituted for one another.
 func main() {
 	mongoURI := getEnv("MONGO_URI", "mongodb://localhost:27017")