Integrate and configure Swagger

[uxabix]

We need to integrate and configure Swagger (OpenAPI) documentation for the Django REST API to improve developer experience, ensure clear API visibility, and simplify frontend/backend collaboration.

---

Requirements

Swagger Integration

• Add Swagger UI and OpenAPI schema generation to the project.
• Use one of the following libraries (choose based on project compatibility):
  • drf-yasg — classic and stable.
  • drf-spectacular — modern, OpenAPI 3 compatible, preferred for new projects.
• Expose Swagger and Redoc documentation endpoints, for example:
  • /api/docs/ → Swagger UI
  • /api/redoc/ → Redoc UI
  • /api/schema/ → raw OpenAPI JSON schema
• Configure the documentation to automatically include:
  • All existing REST API endpoints
  • Auth endpoints (login, register, refresh, etc.)
  • Request/response models with proper serializers and status codes

---

Technical Details

• Add Swagger/Redoc dependencies to requirements.txt.
• Update project URLs (e.g., urls.py) to include schema and UI routes.
• Configure Swagger metadata:
  • API title, version, description
  • Contact and license info (optional)
• If authentication is used (e.g., JWT or TokenAuth):
  • Display authorization header in the Swagger UI (Bearer <token>)
  • Allow interactive testing of secured endpoints
• Ensure the documentation is only accessible in development or staging environments by default.

---

Recommendations (for uncertain points)

• Library choice: Prefer drf-spectacular for better OpenAPI 3 support and long-term maintenance.
• Access control: Add environment-based toggle (e.g., via DEBUG flag) to disable Swagger in production.
• Schema customization: If project uses custom permissions or viewsets, annotate them with @extend_schema decorators for clarity.
• Versioning: Include API version in the schema title (e.g., “Game API v1”).

---

Testing

• Verify that /api/docs/ and /api/redoc/ endpoints load correctly.
• Ensure all existing endpoints are automatically documented.
• Confirm authentication flow works inside the Swagger UI.
• Validate that documentation is hidden or disabled in production mode.

---

Definition of Done

• Swagger/OpenAPI documentation integrated and functional.
• Schema correctly describes all available API endpoints.
• Authentication and authorization mechanisms documented.
• Access restricted to non-production environments.
• Documentation links added to README and developer setup guide.