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

buffalogs/buffalogs/settings/settings.py

@@ -41,6 +41,7 @@
     "rest_framework",
     "rest_framework.authtoken",
     "rest_framework_simplejwt",
+    "drf_spectacular",  # OpenAPI schema generation
     "authentication",
     "corsheaders",
 ]
@@ -235,3 +236,15 @@
         "args": ["weekly"],
     },
 }
+
+# DRF Spectacular Settings for OpenAPI/Swagger Documentation
+REST_FRAMEWORK = {
+    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
+}
+
+SPECTACULAR_SETTINGS = {
+    "TITLE": "BuffaLogs API",
+    "DESCRIPTION": "BuffaLogs is an Open Source Django App for detecting login anomalies and managing security alerts.",
+    "VERSION": "1.0.0",
+    "SERVE_INCLUDE_SCHEMA": False,
+}

buffalogs/buffalogs/urls.py

@@ -1,6 +1,11 @@
 from django.contrib import admin
 from django.urls import include, path
 from impossible_travel.views import alerts, charts, ingestion, logins, users
+from drf_spectacular.views import (
+    SpectacularAPIView,
+    SpectacularRedocView,
+    SpectacularSwaggerView,
+)
 
 urlpatterns = [
     path("admin/", admin.site.urls),
@@ -43,4 +48,8 @@
     path("api/alerters/active-alerter/", alerts.get_active_alerter, name="active_alerter_api"),
     path("api/alerters/<str:alerter>/", alerts.alerter_config, name="alerter_config_api"),
     path("api/alerters/", alerts.get_alerters, name="get_alerters"),
+    # OpenAPI/Swagger Documentation
+    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
+    path("api/docs/", SpectacularSwaggerView.as_view(url_name="schema"), name="swagger-ui"),
+    path("api/redoc/", SpectacularRedocView.as_view(url_name="schema"), name="redoc"),
 ]

buffalogs/requirements.txt

@@ -1,45 +1,77 @@
 # === Core Framework ===
-Django~=5.2                           # Main Django framework (web application, ORM, admin, etc.)
-djangorestframework>=3.16             # Django REST Framework for building RESTful APIs
+
+Django>=5.2  # Main Django framework (web application, ORM, admin, etc.)
+djangorestframework>=3.16  # Django REST Framework for building RESTful APIs
 djangorestframework-simplejwt>=5.5.1  # JWT authentication support for DRF
-django-cors-headers>=4.9.0            # (dev) Enables CORS headers for frontend-backend separation during development
+django-cors-headers>=4.9.0  # (dev) Enables CORS headers for frontend-backend separation during development
+
 
 # === Task Queue / Background Jobs ===
-celery>=5.6                     # Distributed task queue for asynchronous jobs (e.g., scheduled ingestion)
+
+celery>=5.6  # Distributed task queue for asynchronous jobs (e.g., scheduled ingestion)
+
 
 # === Database ===
-psycopg[binary]>=3.2.13           # PostgreSQL database adapter for Python (binary for better performance)
+
+psycopg[binary]>=3.2.13  # PostgreSQL database adapter for Python (binary for better performance)
+
 
 # === Elasticsearch ===
-elasticsearch>=9.2             # Official low-level Python client for Elasticsearch
+
+elasticsearch>=9.2  # Official low-level Python client for Elasticsearch
+
 
 # === Geo & Location ===
-geopy>=2.4.1                     # Library for geocoding and distance calculations via various APIs
+
+geopy>=2.4.1  # Library for geocoding and distance calculations via various APIs
+
 
 # === Date / Time Utilities ===
-python-dateutil>=2.9.0           # Enhanced date parsing, time delta calculations, etc.
+
+python-dateutil>=2.9.0  # Enhanced date parsing, time delta calculations, etc.
+
 
 # === User-Agent Info Parsing ===
-ua-parser>=1.0.1                 # Parses user-agent strings into structured browser/device data
+
+ua-parser>=1.0.1  # Parses user-agent strings into structured browser/device data
+
 
 # === Visualization ===
-pygal>=3.1.0                     # SVG graphing library (used for rendering frontend charts)
-pygal_maps_world>=1.0.2         # World map plugin for Pygal (used in geo-visualizations)
+
+pygal>=3.1.0  # SVG graphing library (used for rendering frontend charts)
+pygal_maps_world>=1.0.2  # World map plugin for Pygal (used in geo-visualizations)
+
 
 # === JWT Utilities ===
-PyJWT>=2.10.1                    # JSON Web Token implementation (may be used directly or via DRF JWT)
+
+PyJWT>=2.10.1  # JSON Web Token implementation (may be used directly or via DRF JWT)
+
 
 # === File handle utilities ===
-PyYAML>=6.0.2                    # To handle yaml files
+
+PyYAML>=6.0.2  # To handle yaml files
+
 
 # === Jinja2 ===
-Jinja2>=3.1.6                   # Templating engine for rendering alert messages
+
+Jinja2>=3.1.6  # Templating engine for rendering alert messages
+
 
 # === Backoff ===
-backoff>=2.2.1                   # Library for retrying operations with exponential backoff
+
+backoff>=2.2.1  # Library for retrying operations with exponential backoff
+
 
 # === HTTP Requests ===
-requests>=2.32.5                 # HTTP library for sending alerts and webhooks
+
+requests>=2.32.5  # HTTP library for sending alerts and webhooks
+
 
 # === Web Server ===
-uwsgi>=2.0.31                   # uWSGI application server for serving Django application
+
+uwsgi>=2.0.31  # uWSGI application server for serving Django application
+
+
+# === API Documentation ===
+
+drf-spectacular>=0.28.0  # OpenAPI/Swagger schema generation for Django REST Framework