Implement Swagger/OpenAPI documentation for Capuchin

[Gautam7352]

Context:

Our current API lacks a standardized, interactive reference, making it difficult for frontend developers and external partners to integrate with our services. We need to implement Swagger to provide a single source of truth for our API contracts.

Objectives:

• Set up a Swagger UI instance accessible at /api-docs or a similar endpoint.

• Document all existing REST endpoints, including HTTP methods (GET, POST, etc.), request parameters, and response schemas.

• Store the definition file (e.g., openapi.yaml) in the /api directory.

Acceptance Criteria (Definition of Done)

1. Endpoint Metadata: All endpoints include a summary, description, and tags for grouping.
2. Request/Response Models: Every endpoint has defined JSON schemas for 200 OK and common error codes (400, 401, 404, 500).
3. Authentication: Security schemes (e.g., Bearer Token, API Key) are correctly defined and testable via the "Try it out" button.
4. Validation: The final yaml/json file passes validation using the Swagger Editor or a CI linting tool.
5. Accessibility: Documentation is served locally and in the staging environment for review.

Implementation Suggestions
For Go: Consider using swaggo/swag to generate documentation directly from code comments.
Manual: Use Swagger Inspector to quickly generate initial definitions from live endpoints.