📝 docs: comprehensive Swagger documentation skill with hierarchical tagging

adr/0013-openapi-swagger-toolchain.md

@@ -309,20 +309,92 @@ go install github.com/swaggo/swag/cmd/swag@latest
 // @BasePath /api
 package main
 
-# 3. Annotate handlers and models
+# 3. Annotate handlers and models with hierarchical tags
 // @Summary Get personalized greeting
 // @Description Returns a greeting with the specified name
-// @Tags greet
+// @Tags API/v1/Greeting  # Hierarchical tag: Domain/Version/Function
 // @Accept json
 // @Produce json
 // @Param name path string true "Name to greet"
 // @Success 200 {object} GreetResponse
 // @Failure 400 {object} ErrorResponse
 // @Router /v1/greet/{name} [get]
+
+# Example v2 endpoint with hierarchical tag
+// @Summary Get greeting (v2)
+// @Description Returns a greeting message with validation (v2)
+// @Tags API/v2/Greeting  # Hierarchical tag: Domain/Version/Function
+// @Accept json
+// @Produce json
+// @Param request body GreetRequest true "Greeting request"
+// @Success 200 {object} GreetResponseV2
+// @Failure 400 {object} ValidationError
+// @Router /v2/greet [post]
+
+# System endpoints use different domain
+// @Summary Health check
+// @Description Check if the service is healthy
+// @Tags System/Health  # Hierarchical tag: Domain/Function
+// @Accept json
+// @Produce json
+// @Success 200 {object} map[string]string "Service is healthy"
+// @Router /health [get]
 func (h *apiV1GreetHandler) handleGreetPath(w http.ResponseWriter, r *http.Request) {
     // handler implementation
 }
 
+## Tagging Strategy Evolution
+
+### Phase 1: Simple Tags (Initial Approach)
+```go
+// @Tags greet
+// @Tags health
+```
+**Issue**: No version separation, all endpoints mixed together
+
+### Phase 2: Version-Based Tags (Improved)
+```go
+// @Tags v1-greet
+// @Tags v2-greet
+// @Tags health
+```
+**Issue**: Still flat structure, no domain separation
+
+### Phase 3: Hierarchical Tags (Current - Recommended)
+```go
+// @Tags API/v1/Greeting
+// @Tags API/v2/Greeting
+// @Tags System/Health
+```
+**Benefits**:
+- Clear domain separation (API vs System)
+- Version organization within domains
+- Natural hierarchy in Swagger UI
+- Scalable for future growth
+
+## Hierarchical Tagging Best Practices
+
+### 1. Domain-First Organization
+- `API/` for business endpoints
+- `System/` for infrastructure endpoints
+- `Admin/` for administrative endpoints
+- `Internal/` for internal-only endpoints
+
+### 2. Consistent Structure
+- API Domain: `API/{version}/{function}`
+- System Domain: `System/{function}`
+- Admin Domain: `Admin/{function}`
+
+### 3. Versioning Strategy
+- Use semantic versions: `v1`, `v2`, `v3`
+- Keep versions consistent across domains
+- Document breaking changes clearly
+
+### 4. Function Naming
+- Use singular nouns: `Greeting`, `User`, `Order`
+- Be specific: `PaymentProcessing` vs `Payment`
+- Avoid acronyms unless widely known
+
 # 4. Generate documentation
 go generate ./pkg/server/