📝 Create API documentation with OpenAPI spec

[jobbykings]

Summary

The existing docs/api/openapi.yaml is minimal. A complete OpenAPI spec would help frontend/backend integration.

Tasks

• Document all API endpoints with request/response schemas
• Add authentication documentation
• Generate interactive docs with Swagger UI
• Keep spec in sync with actual API via CI check

Acceptance Criteria

• All endpoints documented in OpenAPI spec
• Swagger UI accessible at /api-docs