Add interactive API docs at /docs using Scalar

bricef · claude · bricef · commit 1f980e42e653 · 2026-04-01T02:08:10.000+01:00
Serves a Scalar API reference UI that renders the OpenAPI spec from
/openapi.json. Single embedded HTML page, loads Scalar from CDN.
Landing page updated to link to /docs instead of raw /openapi.json.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/internal/http/apidocs.html b/internal/http/apidocs.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>TaskFlow API</title>
+</head>
+<body>
+  <script id="api-reference" data-url="/openapi.json"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>
diff --git a/internal/http/landing.html b/internal/http/landing.html
@@ -76,7 +76,7 @@ <h1>TaskFlow</h1>
   <p class="tagline">Kanban boards with workflow state machines, built for human + AI collaboration.</p>
   <div class="links">
     <a class="primary" href="/dashboard">Dashboard</a>
-    <a class="secondary" href="/openapi.json">API Spec</a>
+    <a class="secondary" href="/docs">API Docs</a>
     <a class="secondary" href="/health">Health</a>
     <a class="secondary" href="https://github.com/bricef/taskflow">GitHub</a>
   </div>
diff --git a/internal/http/routes.go b/internal/http/routes.go
@@ -18,6 +18,9 @@ import (
 //go:embed landing.html
 var landingPage []byte
 
+//go:embed apidocs.html
+var apiDocsPage []byte
+
 // Route is the HTTP-layer representation of a domain resource or operation.
 type Route struct {
 	Name    string
@@ -213,6 +216,10 @@ func (s *Server) registerRoutes() {
 		w.Header().Set("Content-Type", "application/json")
 		w.Write(s.openAPISpec)
 	})
+	r.Get("/docs", func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		w.Write(apiDocsPage)
+	})
 
 	// Authenticated routes — derived from resources and operations.
 	r.Group(func(r chi.Router) {
