Add API documentation with OpenAPI/Swagger

[clencyc]

Description

Generate interactive API documentation with Swagger/OpenAPI so contributors can easily understand and test endpoints.

Acceptance Criteria

• OpenAPI spec generated from code
• Swagger UI available at /api/docs
• All endpoints documented:
  • Request/response schemas
  • Required parameters and headers
  • Error responses (400, 401, 404, 500)
  • Example requests and responses
• Can test endpoints directly in Swagger UI
• Spec file: openapi.yaml
• GH Pages or auto-hosted documentation
• README updated with API docs link

Implementation Details

• Use flask-restx or flasgger for auto-generation
• Decorate endpoints with OpenAPI decorators
• Document all query params, body schema, responses
• Include authentication requirements
• Example: auth header, request body, response

Tools

• flasgger - simple Flask-native solution
• flask-restx - more powerful, full REST framework
• Recommendation: Start with flasgger for quick wins

Difficulty: Medium

Estimated time: 4-5 hours