[ENHANCEMENT] Add Comprehensive OpenAPI/Swagger Documentation for REST APIs

[shivraj1182]

Description

BuffaLogs currently has REST APIs for managing users, alerts, logins, and other resources, but lacks comprehensive interactive API documentation. Adding OpenAPI/Swagger documentation would significantly improve the developer experience and make it easier for users to understand and interact with the API.

Current State

The docs/rest-apis.md file exists but contains minimal information ("API reference converted from the wiki"). The REST APIs are defined in buffalogs/buffalogs/urls.py but lack:

• Interactive documentation
• Request/response schemas
• Example payloads
• Authentication details
• Endpoint descriptions

Proposed Enhancement

Implement comprehensive OpenAPI/Swagger documentation using drf-spectacular or similar tools to:

1. Auto-generate API documentation from Django REST Framework views and serializers
2. Provide interactive UI (Swagger UI/ReDoc) for testing API endpoints
3. Document all endpoints including:
   • User management APIs (/api/users/)
   • Alert APIs (/api/alerts/, /api/alerts/types/, /api/alerts/recent/)
   • Login APIs (/api/logins/)
   • Authentication endpoints
4. Include request/response examples with proper schemas
5. Document authentication mechanisms and required permissions

Benefits

• Improved Developer Experience: Developers can understand and test APIs without reading source code
• Better Integration: External tools can easily integrate with BuffaLogs using the OpenAPI spec
• Reduced Support Burden: Self-documenting APIs reduce questions about endpoint usage
• Professional Standards: OpenAPI is an industry standard for REST API documentation
• GSoC Contribution: This would be a valuable contribution aligned with BuffaLogs' participation in GSoC 2025

Implementation Approach

1. Add drf-spectacular to project dependencies
2. Configure OpenAPI schema generation in Django settings
3. Add docstrings and schema definitions to existing API views/serializers
4. Set up Swagger UI and ReDoc endpoints
5. Update documentation to reference the new interactive API docs
6. Add examples and descriptions for all endpoints

References

• drf-spectacular
• OpenAPI Specification
• Similar implementation in IntelOwl (related project)

Additional Context

I would love to work on this enhancement as it aligns with my interest in improving open-source documentation and developer tools. I'm familiar with Django REST Framework and OpenAPI specifications.

Could you please assign this issue to me if it aligns with the project's roadmap? Happy to discuss the implementation approach or any modifications needed.

[Lorygold]

yea, great issue, I'll assign it to you.

Regarding the GSoC, we’re still figuring out whether BuffaLogs will take part in GSoC this year.