feat: implement OpenAPI/Swagger documentation with swaggo/swag

📝 docs: add comprehensive API documentation
📦 dependencies: add swaggo/swag to go.mod
🔧 chore: add go:generate directive for documentation

- Add comprehensive API documentation using swaggo/swag
- Embed OpenAPI spec in binary using go:embed
- Add Swagger UI at /swagger/
- Document all endpoints, models, and validation rules
- Add go:generate directive for easy regeneration
- Update README, AGENTS, CHANGELOG with documentation
- Finalize ADR 0013 with implementation details
- Gitignore generated docs directory

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
2026-04-05 00:45:40 +02:00
parent 15fcb265bd
commit b279a31f88
12 changed files with 371 additions and 38 deletions

View File

@@ -114,6 +114,39 @@ echo "## Compact History (Last 5 Entries)" > CHANGELOG.md
git log -5 --pretty=format:"### %ad%n- %s%n" -- CHANGELOG.md >> CHANGELOG.md
```
## 2026-04-05 - OpenAPI Documentation Implementation
### ✅ Completed
- **OpenAPI/Swagger Integration**: Added comprehensive API documentation using swaggo/swag
- **Embedded Documentation**: OpenAPI spec embedded in binary using `//go:embed` directive
- **Interactive Swagger UI**: Available at `/swagger/` with try-it-out functionality
- **Code Generation**: Added `//go:generate` directive for easy documentation regeneration
- **Clean Structure**: Documentation in `pkg/server/docs/` (gitignored)
### 📝 Changes
- `cmd/server/main.go`: Added swagger metadata annotations
- `pkg/greet/api_v1.go`: Documented v1 endpoints and models
- `pkg/greet/api_v2.go`: Documented v2 endpoint
- `pkg/server/server.go`: Added embed directive and swagger routes
- `.gitignore`: Added `pkg/server/docs/`
- `go.mod/go.sum`: Added swaggo dependencies
### 🔧 Workflow
```bash
# Generate documentation
go generate ./pkg/server/
# Access documentation
# Swagger UI: http://localhost:8080/swagger/
# OpenAPI spec: http://localhost:8080/swagger/doc.json
```
### 📚 Documentation
- All API endpoints documented with summaries, descriptions, parameters
- Request/response models with examples
- Validation rules and error responses
- Tags for logical grouping
## References
- **Agent Config**: `/Users/gabrielradureau/Work/Vibe/.mistral/dancelessonscoachprogrammer-agent.toml`