# 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
```bash
# Regenerate all Swagger documentation
go generate ./pkg/server/
```

### 2. Verify Structure
```bash
# 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
```bash
# 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
```bash
# These flags are CRITICAL for multi-package projects
--parseDependency  # Parse dependent packages
--parseInternal   # Include internal packages
```

### Embed Directive
```go
//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](adr/0013-openapi-swagger-toolchain.md)** - Architectural decision
- **[AGENTS.md](#openapi-documentation)** - Project documentation
- **[swaggo/swag](https://github.com/swaggo/swag)** - Official documentation

---

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