✨ feat: implement OpenAPI/Swagger documentation with swaggo/swag

📝 docs: add comprehensive API documentation
📦 dependencies: add swaggo/swag to go.mod
🔧 chore: add go:generate directive for documentation

- Add comprehensive API documentation using swaggo/swag
- Embed OpenAPI spec in binary using go:embed
- Add Swagger UI at /swagger/
- Document all endpoints, models, and validation rules
- Add go:generate directive for easy regeneration
- Update README, AGENTS, CHANGELOG with documentation
- Finalize ADR 0013 with implementation details
- Gitignore generated docs directory

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

pkg/server/server.go

@@ -1,25 +1,33 @@
+//go:generate swag init -g ../../cmd/server/main.go
+
 package server
 
 import (
 	"context"
+	"embed"
 	"net"
 	"net/http"
 	"os/signal"
 	"syscall"
 	"time"
 
+	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
+	"github.com/rs/zerolog/log"
+	httpSwagger "github.com/swaggo/http-swagger"
+
 	"DanceLessonsCoach/pkg/config"
 	"DanceLessonsCoach/pkg/greet"
 	"DanceLessonsCoach/pkg/telemetry"
 	"DanceLessonsCoach/pkg/validation"
+
 	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
-
-	"github.com/go-chi/chi/v5"
-	"github.com/go-chi/chi/v5/middleware"
-	"github.com/rs/zerolog/log"
 )
 
+//go:embed docs/swagger.json
+var swaggerJSON embed.FS
+
 type Server struct {
 	router         *chi.Mux
 	readyCtx       context.Context
@@ -75,6 +83,22 @@ func (s *Server) setupRoutes() {
 			s.registerApiV2Routes(r)
 		})
 	}
+
+	// Add Swagger UI with embedded spec
+	// Serve the embedded swagger.json file
+	s.router.Handle("/swagger/doc.json", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		data, err := swaggerJSON.ReadFile("docs/swagger.json")
+		if err != nil {
+			log.Error().Err(err).Msg("Failed to read embedded swagger.json")
+			http.Error(w, "Failed to read swagger.json", http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Write(data)
+	}))
+
+	// Setup Swagger UI handler
+	s.router.Get("/swagger/*", httpSwagger.WrapHandler)
 }
 
 func (s *Server) registerApiV1Routes(r chi.Router) {
@@ -109,11 +133,28 @@ func (s *Server) getAllMiddlewares() []func(http.Handler) http.Handler {
 	return middlewares
 }
 
+// handleHealth godoc
+// @Summary Health check
+// @Description Check if the service is healthy
+// @Tags health
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]string "Service is healthy"
+// @Router /health [get]
 func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
 	log.Trace().Msg("Health check requested")
 	w.Write([]byte(`{"status":"healthy"}`))
 }
 
+// handleReadiness godoc
+// @Summary Readiness check
+// @Description Check if the service is ready to accept traffic
+// @Tags health
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]bool "Service is ready"
+// @Failure 503 {object} map[string]bool "Service is not ready"
+// @Router /ready [get]
 func (s *Server) handleReadiness(w http.ResponseWriter, r *http.Request) {
 	log.Trace().Msg("Readiness check requested")