feature(documentation): Add rest API documentation

- Use `drf-yasg` library to generate `swagger` and `redoc` API documentation
  user interfaces
- Use docstrings and 'drf_yasg.utils.swagger_auto_schema` in `views.py`
  to document the api views

[Finishes #164046244]

README.md

@@ -34,6 +34,10 @@ Authors Haven app can be run by:
     Run the app according to the environment you need:
 
    #### Development environment:
+    `python manage.py makemigrations --settings=authors.settings.dev`
+
+    `python manage.py migrate --settings=authors.settings.dev`
+
     `python manage.py runserver --settings=authors.settings.dev`
 
    #### Testing environment:

authors/apps/authentication/views.py

@@ -4,17 +4,25 @@
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
+from drf_yasg.utils import swagger_auto_schema
+
 from .renderers import UserJSONRenderer
 from .serializers import (LoginSerializer, RegistrationSerializer,
                           UserSerializer)
 
 
 class RegistrationAPIView(APIView):
+    """
+    post:
+        Register a new user by creating a new user instance.
+    """
     # Allow any user (authenticated or not) to hit this endpoint.
     permission_classes = (AllowAny,)
     renderer_classes = (UserJSONRenderer,)
     serializer_class = RegistrationSerializer
 
+    @swagger_auto_schema(query_serializer=RegistrationSerializer,
+                         responses={201: UserSerializer()})
     def post(self, request):
         user = request.data.get('user', {})
 
@@ -29,10 +37,16 @@ def post(self, request):
 
 
 class LoginAPIView(APIView):
+    """
+    post:
+        Login an exising user
+    """
     permission_classes = (AllowAny,)
     renderer_classes = (UserJSONRenderer,)
     serializer_class = LoginSerializer
 
+    @swagger_auto_schema(query_serializer=LoginSerializer,
+                         responses={200: UserSerializer()})
     def post(self, request):
         user = request.data.get('user', {})
 
@@ -47,6 +61,16 @@ def post(self, request):
 
 
 class UserRetrieveUpdateAPIView(RetrieveUpdateAPIView):
+    """
+    get:
+        Retrieve details of a user
+
+    put:
+        Update all details of a user
+
+    patch:
+        Update a single detail of a user
+    """
     permission_classes = (IsAuthenticated,)
     renderer_classes = (UserJSONRenderer,)
     serializer_class = UserSerializer

authors/settings/base.py

@@ -39,6 +39,7 @@
 
     'django_extensions',
     'rest_framework',
+    'drf_yasg',
 
     'authors.apps.authentication',
     'authors.apps.core',

authors/urls.py

@@ -14,11 +14,39 @@
     2. Add a URL to urlpatterns:  url(r'^blog/', include('blog.urls'))
 """
 from django.urls import include, path
+from django.conf.urls import url
 from django.contrib import admin
 
+from rest_framework import permissions
+
+
+from drf_yasg.views import get_schema_view
+from drf_yasg import openapi
+
+
+schema_view = get_schema_view(
+    openapi.Info(
+        title="Legion: Author's Haven",
+        default_version='v1',
+        description="Author's Haven",
+        terms_of_service="",
+        contact=openapi.Contact(email=""),
+        license=openapi.License(name=""),
+    ),
+    public=True,
+    permission_classes=(permissions.AllowAny,),
+)
+
 
 urlpatterns = [
     path('admin/', admin.site.urls),
     path('api/', include('authors.apps.authentication.urls',
                          namespace='authentication')),
+    url(r'^swagger(?P<format>\.json|\.yaml)$',
+        schema_view.without_ui(cache_timeout=0),
+        name='schema-json'),
+    url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0),
+        name='schema-swagger-ui'),
+    url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0),
+        name='schema-redoc'),
 ]

requirements.txt

@@ -30,3 +30,5 @@ typed-ast==1.3.1
 urllib3==1.24.1
 whitenoise==4.1.2
 wrapt==1.11.1
+coreapi==2.3.3
+drf-yasg==1.13.0