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

---
name: swagger-documentation
description: Manage and optimize OpenAPI/Swagger documentation for dance-lessons-coach
license: MIT
metadata:
  author: dance-lessons-coach Team
  version: "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
```bash
# Install swaggo/swag
go install github.com/swaggo/swag/cmd/swag@latest
```

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

### Go Generate Directive
```go
//go:generate swag init -g ../../cmd/server/main.go --parseDependency --parseInternal
```

## 🏷️ Hierarchical Tagging System

### Current Standard
```go
// 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
```go
// 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
```go
// 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
```go
// 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
```go
// 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](https://github.com/swaggo/swag)
- [swaggo/swag Documentation](https://github.com/swaggo/swag#declaration)
- [OpenAPI 2.0 Specification](https://swagger.io/specification/v2/)

### dance-lessons-coach Specific
- [ADR 0013: OpenAPI/Swagger Toolchain](adr/0013-openapi-swagger-toolchain.md)
- [AGENTS.md OpenAPI Section](#openapi-documentation)
- [Current Implementation](pkg/greet/api_v1.go)

## 🤖 Automation Scripts

### Regenerate Documentation
```bash
#!/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
```bash
#!/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