Add OpenAPI spec validation with vacuum

Author: pierres

.github/workflows/ci.yml

@@ -17,6 +17,8 @@ jobs:
               run: just build-templates
             - name: Run Linter
               run: just lint
+            - name: Validate OpenAPI Spec
+              run: just check-spec
 
     test:
         runs-on: ubuntu-latest

internal/apidoc/handler.go

@@ -2,6 +2,7 @@ package apidoc
 
 import (
 	"encoding/json"
+	"io"
 	"net/http"
 )
 
@@ -26,3 +27,8 @@ func (h *Handler) HandleDocJSON(w http.ResponseWriter, _ *http.Request) {
 func (h *Handler) RegisterRoutes(mux *http.ServeMux) {
 	mux.HandleFunc("GET /api/doc.json", h.HandleDocJSON)
 }
+
+func PrintSpec(w io.Writer, includeInternal bool) {
+	data, _ := json.MarshalIndent(BuildSpec(includeInternal), "", "    ")
+	_, _ = w.Write(data)
+}

internal/apidoc/spec.go

@@ -14,8 +14,9 @@ type OpenAPISpec struct {
 }
 
 type SpecInfo struct {
-	Title   string `json:"title"`
-	Version string `json:"version"`
+	Title       string `json:"title"`
+	Version     string `json:"version"`
+	Description string `json:"description,omitempty"`
 }
 
 type SpecTag struct {
@@ -233,8 +234,9 @@ func BuildSpec(includeInternal bool) *OpenAPISpec {
 	spec := &OpenAPISpec{
 		OpenAPI: "3.0.0",
 		Info: SpecInfo{
-			Title:   "pkgstats API documentation",
-			Version: "3.0.0",
+			Title:       "pkgstats API documentation",
+			Version:     "3.0.0",
+			Description: "Read-only API for Arch Linux package popularity statistics.",
 		},
 		Paths:      make(map[string]PathItem),
 		Components: SpecComponents{Schemas: make(map[string]*Schema)},

justfile

@@ -61,6 +61,15 @@ lint:
     golangci-lint run
     just --fmt --unstable --check
 
+# validate the OpenAPI spec
+check-spec:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    spec=$(mktemp --suffix=.json)
+    trap 'rm -f "$spec"' EXIT
+    go run -tags development . spec > "$spec"
+    go run github.com/daveshanley/vacuum@latest lint -bx -r vacuum.conf.yaml "$spec"
+
 # auto-format all code
 fmt:
     pnpm run format

main.go

@@ -28,6 +28,11 @@ import (
 const defaultCacheMaxAge = 5 * time.Minute
 
 func main() {
+	if isDevelopment && len(os.Args) > 1 && os.Args[1] == "spec" {
+		apidoc.PrintSpec(os.Stdout, true)
+		return
+	}
+
 	cfg, err := config.Load()
 	if err != nil {
 		slog.Error("failed to load config", "error", err)

vacuum.conf.yaml

@@ -0,0 +1,6 @@
+extends: [[vacuum:oas, recommended]]
+rules:
+  description-duplication: false
+  oas3-missing-example: false
+  oas3-api-servers: false
+  component-description: false