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

Swagger Documentation Skill

Skill Name: swagger-documentation Status: ✅ Active Version: 1.0.0

📋 Overview

This skill provides comprehensive guidance and automation for managing OpenAPI/Swagger documentation in the dance-lessons-coach project. It captures our best practices, tagging strategies, and automation patterns for maintaining high-quality API documentation.

🎯 Key Features

1. Hierarchical Tagging System

Our proprietary Domain/Version/Function tagging structure:

• API/v1/Greeting, API/v2/Greeting for business endpoints
• System/Health, System/Metrics for infrastructure endpoints
• Clear separation between API domains and versions

2. Standardized Annotations

Pre-defined templates for all endpoint types:

• Basic endpoints
• Parameterized endpoints
• POST endpoints with request bodies
• System/health endpoints

3. Automation Scripts

Ready-to-use scripts for:

• Documentation generation
• Validation and quality checks
• CI/CD integration

4. Best Practices Guide

Comprehensive guidelines covering:

• Tag consistency rules
• Annotation completeness
• Version management
• Response documentation

🚀 Quick Start

1. Generate Documentation

# Regenerate all Swagger documentation
go generate ./pkg/server/

2. Verify Structure

# Check hierarchical tags are present
grep -c "API/v1/Greeting" pkg/server/docs/swagger.json
grep -c "API/v2/Greeting" pkg/server/docs/swagger.json
grep -c "System/Health" pkg/server/docs/swagger.json

3. Test in Swagger UI

# Access the interactive documentation
open http://localhost:8080/swagger/

📚 Documentation Structure

swagger_documentation/
├── SKILL.md          # Complete skill documentation
├── README.md         # This file
└── scripts/          # Automation scripts (future)

🎓 Usage Patterns

Adding New Endpoints

1. Choose the right tag based on domain/version/function
2. Copy annotation template from SKILL.md
3. Add complete annotations to handler
4. Regenerate documentation with go generate
5. Verify in Swagger UI

Updating Existing Endpoints

1. Update handler code as needed
2. Review annotations for accuracy
3. Regenerate documentation
4. Test changes in Swagger UI

Adding New API Versions

1. Create new tag structure (e.g., API/v3/Greeting)
2. Document in SKILL.md
3. Update ADR 0013 with rationale
4. Implement endpoints with new tags
5. Regenerate and test

🔧 Technical Details

Tag Structure Rules

Domain/Version/Function
│      │        └─ Specific functionality (Greeting, User, Health)
│      └─ API version (v1, v2, v3) - for API domain only
└─ Domain (API, System, Admin)

Required Flags

# These flags are CRITICAL for multi-package projects
--parseDependency  # Parse dependent packages
--parseInternal   # Include internal packages

Embed Directive

//go:embed docs/swagger.json
var swaggerJSON embed.FS

📝 Maintenance

Updating This Skill

When you:

• Introduce new tag patterns
• Discover better annotation approaches
• Add new endpoint types
• Find solutions to common issues

Please update SKILL.md to share knowledge with the team!

Version History

• 1.0.0: Initial release with hierarchical tagging
• Next: Add CI/CD integration scripts

🤝 Contributing

Found a better way? Have a new pattern?

1. Update SKILL.md with your improvements
2. Test thoroughly in development
3. Document examples clearly
4. Update ADR 0013 if architectural changes
5. Commit with clear message using gitmoji

📚 Related Resources

• ADR 0013 - Architectural decision
• AGENTS.md - Project documentation
• swaggo/swag - Official documentation

---

Maintained by: dance-lessons-coach Team
License: MIT
Status: Actively developed