Add integration instructions for drf-yasg

Makefile

@@ -41,7 +41,8 @@ build-docs:
 		rest_framework_simplejwt/compat.py \
 		rest_framework_simplejwt/exceptions.py \
 		rest_framework_simplejwt/settings.py \
-		rest_framework_simplejwt/state.py
+		rest_framework_simplejwt/state.py \
+		rest_framework_simplejwt/views.py
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(MAKE) -C docs doctest

docs/conf.py

@@ -33,6 +33,7 @@ def django_configure():
     from django.conf import settings
 
     settings.configure(
+        SECRET_KEY="exposed secret key",
         INSTALLED_APPS=(
             'django.contrib.admin',
             'django.contrib.auth',

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

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