Add swagger docs (#1084)

* patch: add requirement for swagger

* feat: add documentation configurations

* patch: add urls paths for apis

* feat: add api description for swagger

* patch: show an accurate example

* patch: add api description

deployment/docker/requirements.txt

@@ -59,6 +59,7 @@ webencodings==0.5.1
 zope.interface==6.1
 djangorestframework==3.14.0
 djangorestframework-simplejwt==5.3.0
+drf-yasg==1.21.7
 PyJWT==2.8.0
 pytz==2023.3.post1
 sentry-sdk==1.14.0

django_project/minisass/settings.py

@@ -6,6 +6,7 @@
 from django.core.files.storage import FileSystemStorage
 
 from minisass.utils import absolute_path
+from drf_yasg import openapi
 
 PROJECT_PATH = os.path.abspath(os.path.dirname(__file__))
 
@@ -93,6 +94,17 @@
     'SLIDING_TOKEN_REFRESH_LIFETIME': timedelta(days=1),
 }
 
+SWAGGER_SETTINGS = {
+    'DEFAULT_INFO': openapi.Info(
+        title="miniSASS API's",
+        default_version='v1',
+        description="Describes the public API's",
+        terms_of_service="minisass.org",
+        contact=openapi.Contact(email=""),
+        license=openapi.License(name="BSD License"),
+    ),
+}
+
 # Password validation
 # https://docs.djangoproject.com/en/4.2/ref/settings/#auth-password-validators
 
@@ -197,6 +209,7 @@
     'django.contrib.sites',
     'django.contrib.messages',
     'django.contrib.staticfiles',
+    'drf_yasg',
     'django.contrib.admin',
     'django.contrib.gis',
     # custom apps here:

django_project/minisass/urls.py

@@ -10,8 +10,23 @@
     GetMobileApp,
     get_announcements
 )
-
 from minisass_frontend.views import ReactHomeView
+from drf_yasg.views import get_schema_view
+from drf_yasg import openapi
+
+
+schema_view = get_schema_view(
+   openapi.Info(
+      title="miniSASS API's",
+      default_version='v1',
+      description="Description of API's",
+      terms_of_service="minisass.org",
+      contact=openapi.Contact(email=""),
+      license=openapi.License(name="BSD License"),
+   ),
+   public=True,
+   permission_classes=(permissions.AllowAny,),
+)
 
 admin.autodiscover()
 
@@ -44,6 +59,10 @@
 
     # google analytics path
     # re_path('djga/', include('google_analytics.urls')),
+
+    path('swagger<format>/', schema_view.without_ui(cache_timeout=0), name='schema-json'),
+    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
+    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
 ]
 
 if settings.DEBUG:

django_project/monitor/site_views.py

@@ -8,6 +8,8 @@
 from rest_framework.parsers import MultiPartParser, FormParser, JSONParser
 from minisass.models import GroupScores
 from django.utils.dateparse import parse_date
+from drf_yasg.utils import swagger_auto_schema
+from drf_yasg import openapi
 
 
 from monitor.serializers import (
@@ -197,6 +199,69 @@ def get(self, request, latitude, longitude):
 
 class SitesWithObservationsView(APIView):
 	serializer_class = SitesAndObservationsSerializer
+	@swagger_auto_schema(
+		operation_description="Retrieve detailed information about a site, including its observations and images.",
+		manual_parameters=[
+			openapi.Parameter(
+				'start_date', 
+				openapi.IN_QUERY, 
+				description="Start date in YYYY-MM-DD format", 
+				type=openapi.TYPE_STRING
+			)
+		],
+		responses={
+			200: openapi.Response(
+				description="Successful response",
+				examples={
+					"application/json": {
+						"site": {
+							"gid": 1,
+							"sitename": "Sample Site",
+							"rivername": "Sample River",
+							"rivercategory": "rocky",
+							"sitedescription": "This is a description of the sample site.",
+							"images": [
+								{
+									"id": 1,
+									"image": "https://minisass.org/path/to/image.jpg"
+								},
+								{
+									"id": 2,
+									"image": "https://example.com/path/to/another-image.jpg"
+								}
+							],
+							"observations": [
+								{
+									"obs_id": 123,
+									"obs_date": "2024-08-21",
+									"ml_score": "5.0",
+									"collector_name": "John Doe",
+									"score": 3.45,
+									"comment": "Observation comment",
+									"is_validated": True,
+									"water_clarity": 2.5,
+									"water_temp": 20.3,
+									"ph": 7.2,
+									"diss_oxygen": 8.5,
+									"diss_oxygen_unit": "mgl",
+									"elec_cond": 0.5,
+									"elec_cond_unit": "mS/m",
+									"images": [
+										{
+											"id": 1,
+											"image": "https://example.com/path/to/obs-image.jpg",
+											"description": "Observation image description"
+										}
+									]
+								}
+							]
+						}
+					}
+				}
+			),
+			400: openapi.Response(description="Invalid date format"),
+		}
+	)
 	def get(self, request):
 		start_date_str = request.query_params.get('start_date', None)
 		start_date = parse_date(start_date_str) if start_date_str else None