如何在 Django REST Framework 中自动创建 API 文档？

先决条件 - https://www.geeksforgeeks.org/how-to-create-an-app-in-django/

编写文档对于开发人员来说可能非常令人生畏，老实说，没有人喜欢编写冗长的解释，我个人不喜欢，但众所周知，文档与编写正常运行的代码同等重要。因此，有一种非常简单的自动生成文档的方法，等等，不仅是文档，我还将向您展示如何创建一个在线游乐场来测试 API。

我不了解您，但对我而言，Django 是 Web 开发的必备框架，因此我将向您展示如何在 Django 中执行此操作。因此，在我们开始之前，您需要安装Django和Django REST Framework 。我假设你已经有了。接下来，您需要安装drf-yasg 。为此，只需在终端中键入以下内容。

pip install drf-yasg

现在，让我们从步骤开始。

首先，创建一个新的 Django 项目。我假设您已经知道如何做到这一点。

接下来，转到settings.py并将drf_yasg添加到INSTALLED_APPS

INSTALLED_APPS = [
   ...
   'drf_yasg',
   ...
]

然后，进入urls.py并添加 drf_yasg的驱动程序代码

Python3

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="Dummy API",
      default_version='v1',
      description="Dummy description",
      terms_of_service="https://www.google.com/policies/terms/",
      contact=openapi.Contact(email="contact@dummy.local"),
      license=openapi.License(name="BSD License"),
   ),
   public=True,
   permission_classes=(permissions.AllowAny,),
)
  
urlpatterns = [
   url(r'^playground/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
   url(r'^docs/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ...
]

Python3

from drf_yasg.utils import swagger_auto_schema
from rest_framework import status, permissions, serializers
from rest_framework.response import Response
from rest_framework.views import APIView
  
  
class ContactForm(serializers.Serializer):
      # simple serializer for emails
    email = serializers.EmailField()
    message = serializers.CharField()
  
  
# simple endpoint to take the serializer data
class SendEmail(APIView):
      # permission class set to be unauthenticated
    permission_classes = (permissions.AllowAny,)
    # this is where the drf-yasg gets invoked
    @swagger_auto_schema(request_body=ContactForm)
    def post(self, request):
          # serializer object
        serializer = ContactForm(data=request.data)
        # checking for errors
        if serializer.is_valid():
            json = serializer.data
            return Response(
                data={"status": "OK", "message": json},
                status=status.HTTP_201_CREATED,
            )
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

现在，如果您简单地运行服务器并转到 localhost:8000/docs，您可以看到文档，如果您转到 localhost:8000/playground 但等待文档显示的内容，我们还没有创建任何路由来显示文档。因此，让我们快速创建一个新应用并为其添加路由。

首先，创建一个名为demo的应用程序。我假设您已经知道如何创建应用程序并将其添加到 Django 设置以及 url。

接下来，转到demo/views.py并将以下代码添加到其中。

蟒蛇3

from drf_yasg.utils import swagger_auto_schema
from rest_framework import status, permissions, serializers
from rest_framework.response import Response
from rest_framework.views import APIView
  
  
class ContactForm(serializers.Serializer):
      # simple serializer for emails
    email = serializers.EmailField()
    message = serializers.CharField()
  
  
# simple endpoint to take the serializer data
class SendEmail(APIView):
      # permission class set to be unauthenticated
    permission_classes = (permissions.AllowAny,)
    # this is where the drf-yasg gets invoked
    @swagger_auto_schema(request_body=ContactForm)
    def post(self, request):
          # serializer object
        serializer = ContactForm(data=request.data)
        # checking for errors
        if serializer.is_valid():
            json = serializer.data
            return Response(
                data={"status": "OK", "message": json},
                status=status.HTTP_201_CREATED,
            )
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

之后，将此APIView添加到urls.py到/email端点。就是这样。现在，如果您只是在localhost上的端口8000上运行服务器，然后转到localhost:8000/docs ，您应该会看到文档，并且可以在localhost:8000/playground上查看 Playground。它应该看起来像这些。

文档

操场