✨ 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/greet/api_v1.go

@@ -9,6 +9,48 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
+// GreetResponse represents a greeting response
+// @Description GreetResponse represents a greeting response with a message
+// @Property message string "The greeting message" example("Hello John!")
+type GreetResponse struct {
+	Message string `json:"message" example:"Hello John!"`
+}
+
+// GreetRequest represents a greeting request
+// @Description GreetRequest represents a request with a name to greet
+// @Property name string "The name to greet" example("John")
+type GreetRequest struct {
+	Name string `json:"name" example:"John"`
+}
+
+// ErrorResponse represents an error response
+// @Description ErrorResponse represents an error response
+type ErrorResponse struct {
+	Error   string `json:"error" example:"invalid_request"`
+	Message string `json:"message" example:"Invalid name parameter"`
+}
+
+// GreetResponseV2 represents a v2 greeting response
+// @Description GreetResponseV2 represents a v2 greeting response
+type GreetResponseV2 struct {
+	Message string `json:"message" example:"Hello my friend John!"`
+}
+
+// ValidationError represents a validation error response
+// @Description ValidationError represents a validation error with details
+type ValidationError struct {
+	Error   string             `json:"error" example:"validation_failed"`
+	Message string             `json:"message" example:"Invalid request data"`
+	Details []ValidationDetail `json:"details,omitempty"`
+}
+
+// ValidationDetail represents a single validation error detail
+// @Description ValidationDetail represents a single field validation error
+type ValidationDetail struct {
+	Field string `json:"field" example:"name"`
+	Error string `json:"error" example:"must be <= 100 characters"`
+}
+
 type Greeter interface {
 	Greet(ctx context.Context, name string) string
 }
@@ -32,11 +74,29 @@ func (h *apiV1GreetHandler) RegisterRoutes(router chi.Router) {
 	log.Trace().Msg("Greet routes registered")
 }
 
+// handleGreetQuery godoc
+// @Summary Get default greeting
+// @Description Returns a default greeting message
+// @Tags greet
+// @Accept json
+// @Produce json
+// @Success 200 {object} GreetResponse "Successful response"
+// @Router /v1/greet [get]
 func (h *apiV1GreetHandler) handleGreetQuery(w http.ResponseWriter, r *http.Request) {
 	name := r.URL.Query().Get("name")
 	h.writeJSONResponse(w, h.greeter.Greet(r.Context(), name))
 }
 
+// handleGreetPath godoc
+// @Summary Get personalized greeting
+// @Description Returns a greeting with the specified name
+// @Tags greet
+// @Accept json
+// @Produce json
+// @Param name path string true "Name to greet"
+// @Success 200 {object} GreetResponse "Successful response"
+// @Failure 400 {object} ErrorResponse "Invalid name parameter"
+// @Router /v1/greet/{name} [get]
 func (h *apiV1GreetHandler) handleGreetPath(w http.ResponseWriter, r *http.Request) {
 	name := chi.URLParam(r, "name")
 	h.writeJSONResponse(w, h.greeter.Greet(r.Context(), name))

pkg/greet/api_v2.go

@@ -44,6 +44,16 @@ type greetResponse struct {
 	Message string `json:"message"`
 }
 
+// handleGreetPost godoc
+// @Summary Get greeting (v2)
+// @Description Returns a greeting message with validation (v2)
+// @Tags greet
+// @Accept json
+// @Produce json
+// @Param request body GreetRequest true "Greeting request"
+// @Success 200 {object} GreetResponseV2 "Successful response"
+// @Failure 400 {object} ValidationError "Validation error"
+// @Router /v2/greet [post]
 func (h *apiV2GreetHandler) handleGreetPost(w http.ResponseWriter, r *http.Request) {
 	// Read request body
 	body, err := io.ReadAll(r.Body)