Generate OpenAPI spec programmatically instead of maintaining a static file

Replace the hand-written spec.json with Go code in internal/apidoc/spec.go.
The spec is built at startup from an entitySpec table and buildSpec(), covering
all popularity endpoints and the submit endpoint. Internal endpoints (countries,
mirrors, system/OS architectures, submit) are excluded from the production spec
and only included in development/test environments.

Add Config.IsDevelopment() to centralise the environment string comparisons
that were previously scattered across main.go and the apidoc package.

Author: pierres

internal/apidoc/handler.go

@@ -1,25 +1,29 @@
 package apidoc
 
 import (
-	_ "embed"
+	"encoding/json"
 	"net/http"
 )
 
-//go:embed spec.json
-var specJSON []byte
-
 // Handler handles HTTP requests for the OpenAPI documentation.
-type Handler struct{}
+type Handler struct {
+	specJSON []byte
+}
 
-// NewHandler creates a new Handler.
-func NewHandler() *Handler {
-	return &Handler{}
+// NewHandler creates a new Handler and builds the OpenAPI spec.
+// Internal endpoints are included only when includeInternal is true.
+func NewHandler(includeInternal bool) *Handler {
+	data, err := json.MarshalIndent(buildSpec(includeInternal), "", "    ")
+	if err != nil {
+		panic("apidoc: failed to marshal OpenAPI spec: " + err.Error())
+	}
+	return &Handler{specJSON: data}
 }
 
 // HandleDocJSON handles GET /api/doc.json
 func (h *Handler) HandleDocJSON(w http.ResponseWriter, _ *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
-	_, _ = w.Write(specJSON)
+	_, _ = w.Write(h.specJSON)
 }
 
 // RegisterRoutes registers the API documentation routes on the given mux.

internal/apidoc/handler_test.go

@@ -8,7 +8,7 @@ import (
 )
 
 func TestHandleDocJSON(t *testing.T) {
-	handler := NewHandler()
+	handler := NewHandler(true)
 	mux := http.NewServeMux()
 	handler.RegisterRoutes(mux)
 
@@ -41,4 +41,82 @@ func TestHandleDocJSON(t *testing.T) {
 	if info["title"] != "pkgstats API documentation" {
 		t.Errorf("expected title 'pkgstats API documentation', got %v", info["title"])
 	}
+
+	paths, ok := doc["paths"].(map[string]any)
+	if !ok {
+		t.Fatal("expected paths to be an object")
+	}
+
+	expectedPaths := []string{
+		"/api/packages",
+		"/api/packages/{name}",
+		"/api/packages/{name}/series",
+		"/api/countries",
+		"/api/countries/{code}",
+		"/api/countries/{code}/series",
+		"/api/mirrors",
+		"/api/mirrors/{url}",
+		"/api/mirrors/{url}/series",
+		"/api/system-architectures",
+		"/api/system-architectures/{name}",
+		"/api/system-architectures/{name}/series",
+		"/api/operating-systems",
+		"/api/operating-systems/{id}",
+		"/api/operating-systems/{id}/series",
+		"/api/operating-system-architectures",
+		"/api/operating-system-architectures/{name}",
+		"/api/operating-system-architectures/{name}/series",
+		"/api/submit",
+	}
+
+	for _, p := range expectedPaths {
+		if _, found := paths[p]; !found {
+			t.Errorf("expected path %q in development spec", p)
+		}
+	}
+}
+
+func TestHandleDocJSONProduction(t *testing.T) {
+	handler := NewHandler(false)
+	mux := http.NewServeMux()
+	handler.RegisterRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/doc.json", nil)
+	rr := httptest.NewRecorder()
+	mux.ServeHTTP(rr, req)
+
+	var doc map[string]any
+	if err := json.Unmarshal(rr.Body.Bytes(), &doc); err != nil {
+		t.Fatalf("response is not valid JSON: %v", err)
+	}
+
+	paths, ok := doc["paths"].(map[string]any)
+	if !ok {
+		t.Fatal("expected paths to be an object")
+	}
+
+	publicPaths := []string{
+		"/api/packages",
+		"/api/packages/{name}",
+		"/api/packages/{name}/series",
+	}
+	for _, p := range publicPaths {
+		if _, found := paths[p]; !found {
+			t.Errorf("expected public path %q in production spec", p)
+		}
+	}
+
+	internalPaths := []string{
+		"/api/countries",
+		"/api/mirrors",
+		"/api/system-architectures",
+		"/api/operating-systems",
+		"/api/operating-system-architectures",
+		"/api/submit",
+	}
+	for _, p := range internalPaths {
+		if _, found := paths[p]; found {
+			t.Errorf("internal path %q should not appear in production spec", p)
+		}
+	}
 }