dance-lessons-coach/.vibe/skills/swagger-documentation/SKILL.md

name, description, license, metadata

name	description	license	metadata
swagger-documentation	Manage and optimize OpenAPI/Swagger documentation for dance-lessons-coach	MIT	author version dance-lessons-coach Team 1.0.0

Swagger Documentation Skill

Name: swagger-documentation Purpose: Manage and optimize OpenAPI/Swagger documentation for dance-lessons-coach Version: 1.0.0

🎯 Skill Objectives

1. Standardize Swagger documentation across the project
2. Automate documentation generation and updates
3. Optimize tag organization and structure
4. Validate documentation completeness and accuracy
5. Enhance developer experience with best practices

📋 Skill Capabilities

1. Documentation Generation

• Auto-generate Swagger docs with proper flags
• Handle multi-package projects
• Ensure complete endpoint coverage

2. Tag Management

• Implement hierarchical tagging (Domain/Version/Function)
• Maintain tag consistency
• Document tag evolution

3. Annotation Standards

• Enforce consistent annotation patterns
• Validate annotation completeness
• Provide annotation templates

4. Quality Assurance

• Check for missing documentation
• Validate Swagger JSON/YAML
• Ensure embed directives are correct

🔧 Implementation

Required Tools

# Install swaggo/swag
go install github.com/swaggo/swag/cmd/swag@latest

Standard Command

# Generate documentation with proper flags
swag init -g ./cmd/server/main.go --parseDependency --parseInternal

Go Generate Directive

//go:generate swag init -g ../../cmd/server/main.go --parseDependency --parseInternal

🏷️ Hierarchical Tagging System

Current Standard

// API Domain - Business endpoints
@Tags API/v1/Greeting    # v1 greeting endpoints
@Tags API/v2/Greeting    # v2 greeting endpoints
@Tags API/v1/User        # v1 user endpoints (future)
@Tags API/v2/User        # v2 user endpoints (future)

// System Domain - Infrastructure endpoints
@Tags System/Health     # Health/readiness endpoints
@Tags System/Metrics    # Metrics endpoints (future)
@Tags System/Config     # Configuration endpoints (future)

// Admin Domain - Administrative endpoints
@Tags Admin/User        # User management (future)
@Tags Admin/System      # System administration (future)

Tag Structure Rules

1. Domain First: Always start with domain (API/, System/, Admin/)
2. Version Second: For API domain, include version (v1/, v2/)
3. Function Third: Specific functionality area (Greeting, User, Health)
4. Consistent Capitalization: Use PascalCase for all components

📝 Annotation Templates

Basic Endpoint

// handleGreetQuery godoc
// @Summary Get default greeting
// @Description Returns a greeting message with default parameters
// @Tags API/v1/Greeting
// @Accept json
// @Produce json
// @Success 200 {object} GreetResponse "Successful response"
// @Router /v1/greet [get]
func (h *apiV1GreetHandler) handleGreetQuery(w http.ResponseWriter, r *http.Request) {
    // implementation
}

Parameterized Endpoint

// handleGreetPath godoc
// @Summary Get personalized greeting
// @Description Returns a greeting with the specified name
// @Tags API/v1/Greeting
// @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) {
    // implementation
}

POST Endpoint with Body

// handleGreetPost godoc
// @Summary Create greeting (v2)
// @Description Creates a greeting with validation (v2)
// @Tags API/v2/Greeting
// @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) {
    // implementation
}

System Endpoint

// handleHealth godoc
// @Summary Health check
// @Description Check if the service is healthy
// @Tags System/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) {
    // implementation
}

🎯 Best Practices

1. Tag Consistency

• Use the same tag structure across all similar endpoints
• Don't mix hierarchical and flat tags
• Document new tags in this skill when introduced

2. Annotation Completeness

• Always include: Summary, Description, Tags, Accept, Produce, Responses
• Include Parameters for all path/query/body parameters
• Document all possible response codes

3. Response Documentation

• Use concrete types (GreetResponse) not generics
• Include example values where helpful
• Document both success and error responses

4. Version Management

• Keep version tags consistent (v1, v2, not 1.0, 2.0)
• Document breaking changes in ADR when introducing new versions
• Maintain old versions until formally deprecated

🔍 Validation Checklist

Before Committing Swagger Changes

• Run go generate ./... to regenerate docs
• Verify all endpoints appear in Swagger UI
• Check tag hierarchy is correct
• Validate JSON schema is valid
• Test Swagger UI functionality
• Update this skill if new patterns emerge

Common Issues to Check

1. Missing Endpoints: Ensure all handlers have @Router annotations
2. Incorrect Tags: Verify hierarchical structure
3. Broken References: Check $ref paths in generated JSON
4. Embed Issues: Confirm //go:embed paths are correct
5. Flag Problems: Ensure --parseDependency --parseInternal flags are used

📚 Resources

Official Documentation

• swaggo/swag GitHub
• swaggo/swag Documentation
• OpenAPI 2.0 Specification

dance-lessons-coach Specific

• ADR 0013: OpenAPI/Swagger Toolchain
• AGENTS.md OpenAPI Section
• Current Implementation

🤖 Automation Scripts

Regenerate Documentation

#!/bin/bash
# Regenerate all Swagger documentation
echo "Generating Swagger documentation..."
swag init -g ./cmd/server/main.go --parseDependency --parseInternal

# Move to correct location
rm -rf pkg/server/docs
mkdir -p pkg/server/docs
mv docs/* pkg/server/docs/
rm -rf docs

echo "✅ Swagger documentation generated successfully"

Validate Documentation

#!/bin/bash
# Validate Swagger documentation
echo "Validating Swagger documentation..."

# Check for required endpoints
MISSING_ENDPOINTS=0
for endpoint in "v1/greet" "v2/greet" "health" "ready"; do
    if ! grep -q "$endpoint" pkg/server/docs/swagger.json; then
        echo "❌ Missing endpoint: $endpoint"
        MISSING_ENDPOINTS=$((MISSING_ENDPOINTS + 1))
    fi
done

# Check for hierarchical tags
if ! grep -q "API/v1/Greeting" pkg/server/docs/swagger.json; then
    echo "❌ Missing hierarchical tag: API/v1/Greeting"
fi

if ! grep -q "API/v2/Greeting" pkg/server/docs/swagger.json; then
    echo "❌ Missing hierarchical tag: API/v2/Greeting"
fi

if ! grep -q "System/Health" pkg/server/docs/swagger.json; then
    echo "❌ Missing hierarchical tag: System/Health"
fi

if [ $MISSING_ENDPOINTS -eq 0 ] && [ $MISSING_TAGS -eq 0 ]; then
    echo "✅ Swagger documentation validation passed"
else
    echo "❌ Swagger documentation validation failed"
    exit 1
fi

🎓 Training Guide

For New Developers

1. Understand the hierarchy: Domain/Version/Function
2. Copy existing patterns: Use templates from this skill
3. Generate frequently: Run go generate after changes
4. Test in Swagger UI: Verify your endpoints appear correctly
5. Update documentation: Add new tags to this skill when introduced

Common Mistakes to Avoid

1. Forgetting --parseDependency --parseInternal → Missing endpoints
2. Inconsistent tag structure → Messy Swagger UI
3. Missing @Router annotations → Endpoints not documented
4. Not regenerating after changes → Stale documentation
5. Breaking embed paths → Runtime errors

🔮 Future Enhancements

Potential Improvements

• Add automated documentation testing
• Create Swagger linting rules
• Implement documentation coverage metrics
• Add examples for all response types
• Integrate with CI/CD pipeline

Migration Paths

• OpenAPI 3.0 support when needed
• Automated changelog generation
• Client SDK generation
• API governance tools

📝 Changelog

1.0.0 (2026-04-05): Initial version with hierarchical tagging best practices

• Documented current tag structure
• Added annotation templates
• Included validation checklist
• Added automation scripts
• Established best practices

Next Version: Add automated testing and CI integration

---

Maintainers: dance-lessons-coach Team License: MIT Status: Active