📝 docs: add comprehensive version management and CLI documentation

pkg/server/server.go

@@ -5,6 +5,7 @@ package server
 import (
 	"context"
 	"embed"
+	"fmt"
 	"net"
 	"net/http"
 	"os/signal"
@@ -20,6 +21,7 @@ import (
 	"DanceLessonsCoach/pkg/greet"
 	"DanceLessonsCoach/pkg/telemetry"
 	"DanceLessonsCoach/pkg/validation"
+	"DanceLessonsCoach/pkg/version"
 
 	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
 	sdktrace "go.opentelemetry.io/otel/sdk/trace"
@@ -70,6 +72,9 @@ func (s *Server) setupRoutes() {
 	// Readiness endpoint at root level
 	s.router.Get("/api/ready", s.handleReadiness)
 
+	// Version endpoint at root level
+	s.router.Get("/api/version", s.handleVersion)
+
 	// API routes
 	s.router.Route("/api/v1", func(r chi.Router) {
 		r.Use(s.getAllMiddlewares()...)
@@ -169,6 +174,46 @@ func (s *Server) handleReadiness(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+// handleVersion godoc
+// @Summary Get API version
+// @Description Returns the API version information
+// @Tags System/Version
+// @Accept plain,json
+// @Produce plain,json
+// @Param format query string false "Response format (plain, full, json)" Enums(plain, full, json) default(plain)
+// @Success 200 {string} string "Version information"
+// @Router /version [get]
+func (s *Server) handleVersion(w http.ResponseWriter, r *http.Request) {
+	log.Trace().Msg("Version check requested")
+
+	// Get format parameter
+	format := r.URL.Query().Get("format")
+	if format == "" {
+		format = "plain" // default format
+	}
+
+	switch format {
+	case "plain":
+		w.Header().Set("Content-Type", "text/plain")
+		w.Write([]byte(version.Short()))
+	case "full":
+		w.Header().Set("Content-Type", "text/plain")
+		w.Write([]byte(version.Full()))
+	case "json":
+		w.Header().Set("Content-Type", "application/json")
+		jsonResponse := fmt.Sprintf(`{
+			"version": "%s",
+			"commit": "%s",
+			"built": "%s",
+			"go": "%s"
+		}`, version.Version, version.Commit, version.Date, version.GoVersion)
+		w.Write([]byte(jsonResponse))
+	default:
+		w.Header().Set("Content-Type", "text/plain")
+		w.Write([]byte(version.Short()))
+	}
+}
+
 func (s *Server) Router() http.Handler {
 	return s.router
 }