This skill provides comprehensive guidance and automation for managing OpenAPI/Swagger documentation in the DanceLessonsCoach 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

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

Updating Existing Endpoints

Update handler code as needed
Review annotations for accuracy
Regenerate documentation
Test changes in Swagger UI

Adding New API Versions

Create new tag structure (e.g., API/v3/Greeting)
Document in SKILL.md
Update ADR 0013 with rationale
Implement endpoints with new tags
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?

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

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

Maintained by: DanceLessonsCoach Team
License: MIT
Status: Actively developed

README.md

Swagger Documentation Skill

📋 Overview