feat: API Documentation with OpenAPI/Swagger (Sprint 8)

[fregataa]

Overview

Complete API documentation with OpenAPI/Swagger specification for the config-server.

Goals

• Set up interactive Swagger UI
• Document all API endpoints with OpenAPI 3.0
• Provide API collections and usage guides

Tasks

1. OpenAPI Setup

• Install and configure Swaggo/gin-swagger
• Set up Swagger UI endpoint (/api/docs)
• Configure OpenAPI 3.0 metadata

2. API Annotations

• Add Swagger annotations to namespace handlers
• Add Swagger annotations to group handlers
• Add Swagger annotations to target handlers
• Add Swagger annotations to bootstrap handlers
• Add Swagger annotations to check handlers
• Add Swagger annotations to alert handlers
• Add Swagger annotations to SD handlers

3. Documentation

• Generate OpenAPI spec file
• Add request/response examples
• Document error responses
• Document authentication (prepare for Sprint 9)
• Add API versioning documentation

4. Collections & Guides

• Create Postman collection
• Create Insomnia collection
• Write API usage guide
• Add code examples (curl, Go, Python)

Deliverables

• Complete OpenAPI 3.0 specification
• Interactive Swagger UI
• Postman/Insomnia collections
• API usage guide
• Code examples

Success Criteria

• All endpoints documented
• Swagger UI accessible
• Examples work without modification
• Clear error documentation

Notes

• Update docs as APIs evolve
• Include authentication once Sprint 9 completes