docs: add OpenAPI documentation with Scalar UI

- Add swaggo annotations to all HTTP handlers
- Add Swagger/OpenAPI spec generation with swag
- Create separate docs server binary (drexa-docs)
- Add Makefile with build, run, and docs targets
- Configure Scalar as the API documentation UI

Run 'make docs' to regenerate, 'make run-docs' to serve.

apps/backend/internal/user/http.go

@@ -22,6 +22,15 @@ func (h *HTTPHandler) RegisterRoutes(api fiber.Router) {
 	user.Get("/me", h.getAuthenticatedUser)
 }
 
+// getAuthenticatedUser returns the currently authenticated user
+// @Summary Get current user
+// @Description Retrieve the authenticated user's profile information
+// @Tags users
+// @Produce json
+// @Security BearerAuth
+// @Success 200 {object} User "User profile"
+// @Failure 401 {string} string "Not authenticated"
+// @Router /users/me [get]
 func (h *HTTPHandler) getAuthenticatedUser(c *fiber.Ctx) error {
 	u := reqctx.AuthenticatedUser(c).(*User)
 	if u == nil {

apps/backend/internal/user/user.go

@@ -8,15 +8,20 @@ import (
 	"github.com/uptrace/bun"
 )
 
+// User represents a user account in the system
+// @Description User account information
 type User struct {
-	bun.BaseModel `bun:"users"`
+	bun.BaseModel `bun:"users" swaggerignore:"true"`
 
-	ID          uuid.UUID       `bun:",pk,type:uuid" json:"id"`
-	DisplayName string          `bun:"display_name" json:"displayName"`
-	Email       string          `bun:"email,unique,notnull" json:"email"`
-	Password    password.Hashed `bun:"password,notnull" json:"-"`
-	CreatedAt   time.Time       `bun:"created_at,notnull,nullzero" json:"-"`
-	UpdatedAt   time.Time       `bun:"updated_at,notnull,nullzero" json:"-"`
+	// Unique user identifier
+	ID uuid.UUID `bun:",pk,type:uuid" json:"id" example:"550e8400-e29b-41d4-a716-446655440000"`
+	// User's display name
+	DisplayName string `bun:"display_name" json:"displayName" example:"John Doe"`
+	// User's email address
+	Email       string          `bun:"email,unique,notnull" json:"email" example:"john@example.com"`
+	Password    password.Hashed `bun:"password,notnull" json:"-" swaggerignore:"true"`
+	CreatedAt   time.Time       `bun:"created_at,notnull,nullzero" json:"-" swaggerignore:"true"`
+	UpdatedAt   time.Time       `bun:"updated_at,notnull,nullzero" json:"-" swaggerignore:"true"`
 }
 
 func newUserID() (uuid.UUID, error) {