feat(backend): Add Comprehensive API Documentation with Interactive Swagger

[devJaja]

Summary

Enhance the existing Swagger/OpenAPI documentation with request/response examples, authentication details, error schemas, and interactive testing.

Motivation

Current API documentation lacks examples and authentication details, making it difficult for developers to integrate with the API.

Acceptance Criteria

• All endpoints documented with request/response examples
• Authentication section explains API key and wallet-based auth
• Error response schema documented for all error codes
• Request/response schemas use Zod-generated OpenAPI specs
• Interactive "Try it out" functionality enabled in Swagger UI
• Rate limit headers documented in each endpoint
• WebSocket endpoints documented with message format
• Pagination documented with cursor-based examples
• OpenAPI spec downloadable as JSON/YAML

Files to Modify

File	Action
backend/src/api/docs.ts	New: OpenAPI documentation configuration
backend/src/api/routes/tasks.ts	Add Swagger JSDoc annotations
backend/src/api/routes/agents.ts	Add Swagger JSDoc annotations
backend/src/api/routes/health.ts	Add Swagger JSDoc annotations
backend/src/api/routes/stats.ts	Add Swagger JSDoc annotations
backend/src/api/routes/stream.ts	Add WebSocket documentation
backend/src/api/app.ts	Integrate enhanced Swagger configuration

How to Contribute

1. Create branch feat/enhanced-api-docs
2. Define OpenAPI schemas with examples
3. Add Swagger annotations to all routes
4. Enable interactive testing in Swagger UI
5. Document authentication and error patterns
6. Run npm run build and verify Swagger UI loads

[Nuruddeen61]

Hi team, I’d like to work on this.

I have experience with OpenAPI, Swagger, and Node.js APIs.

Plan:

1. Create docs.ts with OpenAPI config and Zod-generated schemas
2. Add JSDoc Swagger annotations to tasks.ts, agents.ts, health.ts, stats.ts, stream.ts
3. Document API key and wallet auth, error schemas, rate limit headers, and pagination
4. Enable interactive "Try it out" in Swagger UI
5. Add WebSocket docs and downloadable JSON/YAML spec

Will run build and verify UI. PR in 2-3 days.

Thanks, Nuruddeen

[jotel-dev]

I’d like to work on this issue because clear API documentation makes the backend easier to integrate, test, and maintain. I’ll add comprehensive Swagger/OpenAPI documentation, ensure the endpoints and schemas are accurately represented, and provide an interactive interface for developers to explore and test the API.

[grantfox-oss]

🦊 GrantFox — @jotel-dev has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #270)
2. Your PR will be reviewed by the Epta-Node maintainers

Good luck! Track your progress on GrantFox.