Introduce swagger REST API

Author: vyahello

README.md

@@ -78,12 +78,18 @@ Please use `admin` superuser for management.
 
 ### REST Api
 
-Rest api is build with `djangorestframework` followed by https://www.django-rest-framework.org documentation.
+Rest api is build with `djangorestframework` and `drf-yasg` (swagger) libraries.
 
 Here are available api endpoints:
-
-- `/api`: _Retrieves all quotes_
-- `/api/<id>`: _Retrieves a single quote by it's id_
+- `/api`: 
+  - `GET`: _Retrieves all quotes_
+  - `POST`: _Creates a new quote_
+- `/api/<id>`:
+  - `GET`: _Retrieves a single quote by it's id_
+  - `PUT`: _Updates a single quote by it's id_
+  - `DELETE`: _Deletes a quote by it's id_
+
+> Please refer to `/api/docs` endpoint provides a neat swagger REST API documentation.
 
 ### Testing
 

quotes/api/urls.py

@@ -1,10 +1,30 @@
 """Represents URL endpoints for an application."""
 from typing import Any, List
 from django.urls import include, path
+from rest_framework import permissions
+from drf_yasg.views import get_schema_view
+from drf_yasg import openapi
 from .views import QuoteDetail, Quotes
 
+
 urlpatterns: List[Any] = [
     path("", Quotes.as_view()),
     path("<int:pk>", QuoteDetail.as_view()),
     path("api-auth/", include("rest_framework.urls")),
+    path(
+        "docs/",
+        get_schema_view(
+            openapi.Info(
+                title="Quotes REST API",
+                default_version="v1",
+                description="Swagger documentation for Quotes REST API",
+                terms_of_service="https://www.google.com/policies/terms/",
+                contact=openapi.Contact(email="[email protected]"),
+                license=openapi.License(name="MIT License"),
+            ),
+            public=True,
+            permission_classes=(permissions.AllowAny,),
+        ).with_ui("swagger", cache_timeout=0),
+        name="schema-swagger-ui",
+    ),
 ]

quotes/api/views.py

@@ -10,6 +10,10 @@ class Quotes(ListCreateAPIView):
     """Responsible for retrieving all quotes from an application.
 
     Endpoint is `/api/`
+
+    ``GET``: retrieve all quotes
+
+    ``POST``: creates a new quote
     """
 
     queryset: List[Quote] = Quote.objects.all()
@@ -20,6 +24,12 @@ class QuoteDetail(RetrieveUpdateDestroyAPIView):
     """Responsible for retrieving a single quote from an application.
 
     Endpoint is `/api/<id>`
+
+    ``GET``: retrieve a single quote
+
+    ``PUT``: updates a single quote
+
+    ``DELETE``: deletes a single quote
     """
 
     permission_classes = (IsOwnerOrReadOnly,)

quotes/app/models.py

@@ -13,7 +13,7 @@ class Quote(Model):
     cover: Field = URLField(blank=True, null=True)
     added: Field = DateTimeField(auto_now_add=True)
     edited: Field = DateTimeField(auto_now=True)
-    user = ForeignKey(User, on_delete=CASCADE, blank=True, null=True)
+    user: Field = ForeignKey(User, on_delete=CASCADE, blank=True, null=True)
 
     def __str__(self) -> str:
         """Returns quote as a string."""

quotes/manager/settings.py

@@ -30,6 +30,7 @@
     "django.contrib.humanize",
     "django_registration",
     "rest_framework",
+    "drf_yasg",
     "app",
     "api",
 )

requirements.txt

@@ -2,6 +2,7 @@ django==3.0.4
 dj-database-url==0.5.0
 django-registration==3.1
 djangorestframework==3.11.0
+drf-yasg==1.17.1
 requests==2.23.0
 gunicorn==20.0.4 
 psycopg2-binary==2.8.4