Add integration instructions for drf-yasg (#145)

* Add drf-yasg integration page to docs
* Add views.py
* Add SECRET_KEY to docs/conf.py
* Remove Makefile change

Co-authored-by: Andrew Chen Wang <60190294+Andrew-Chen-Wang@users.noreply.github.com>

docs/drf_yasg_integration.rst

@@ -0,0 +1,72 @@
+.. _drf_yasg_integration
+
+``drf-yasg`` Integration
+------------------------
+
+`drf-yasg`_ is a library that automatically generates an OpenAPI schema by
+inspecting DRF ``Serializer`` definitions. Because
+``django-rest-framework-simplejwt`` serializers are not symmetric, if you
+want to generate correct OpenAPI schemas for your JWT token endpoints, use the
+following code to decorate your JWT ``View`` definitions.
+
+.. code-block:: python
+
+    from drf_yasg.utils import swagger_auto_schema
+    from rest_framework import serializers, status
+    from rest_framework_simplejwt.views import (
+        TokenObtainPairView, TokenRefreshView, TokenVerifyView)
+
+
+    class TokenObtainPairResponseSerializer(serializers.Serializer):
+        access = serializers.CharField()
+        refresh = serializers.CharField()
+
+        def create(self, validated_data):
+            raise NotImplementedError()
+
+        def update(self, instance, validated_data):
+            raise NotImplementedError()
+
+
+    class DecoratedTokenObtainPairView(TokenObtainPairView):
+        @swagger_auto_schema(
+            responses={
+                status.HTTP_200_OK: TokenObtainPairResponseSerializer})
+        def post(self, request, *args, **kwargs):
+            return super().post(request, *args, **kwargs)
+
+
+    class TokenRefreshResponseSerializer(serializers.Serializer):
+        access = serializers.CharField()
+
+        def create(self, validated_data):
+            raise NotImplementedError()
+
+        def update(self, instance, validated_data):
+            raise NotImplementedError()
+
+
+    class DecoratedTokenRefreshView(TokenRefreshView):
+        @swagger_auto_schema(
+            responses={
+                status.HTTP_200_OK: TokenRefreshResponseSerializer})
+        def post(self, request, *args, **kwargs):
+            return super().post(request, *args, **kwargs)
+
+
+    class TokenVerifyResponseSerializer(serializers.Serializer):
+        def create(self, validated_data):
+            raise NotImplementedError()
+
+        def update(self, instance, validated_data):
+            raise NotImplementedError()
+
+
+    class DecoratedTokenVerifyView(TokenVerifyView):
+        @swagger_auto_schema(
+            responses={
+                status.HTTP_200_OK: TokenVerifyResponseSerializer})
+        def post(self, request, *args, **kwargs):
+            return super().post(request, *args, **kwargs)
+
+.. _drf-yasg: https://github.com/axnsan12/drf-yasg

docs/index.rst

@@ -53,6 +53,7 @@ Contents
     blacklist_app
     experimental_features
     development_and_contributing
+    drf_yasg_integration
     rest_framework_simplejwt