Gabriel Radureau
30af706590
Skill Improvements: - BDD Testing Skill: Enhanced step templates, debugging guides, and patterns - Gitea Client Skill: Added wiki management, issue tracking, and workflow monitoring - Product Owner Assistant: Improved user story workflow and documentation - Commit Message Skill: Better gitmoji integration and issue referencing - Changelog Manager: Enhanced change tracking and documentation - Skill Creator: Improved skill generation templates and validation - Swagger Documentation: Updated OpenAPI integration guides Key Features: - BDD best practices documentation - Gitea API client with wiki support - User story implementation workflow - Git commit message standardization - Skill development patterns - OpenAPI/Swagger documentation generation Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
150 lines
4.0 KiB
Markdown
150 lines
4.0 KiB
Markdown
# 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 |