Python中如何使用drf_yasg.openapi为WebAPI生成可视化文档

DrF-yasg（简称为drf_yasg）是一个用于在Django REST框架（DRF）中生成可视化API文档的Python库。它是基于Swagger和OpenAPI规范的。

在本文中，我将向您介绍如何使用drf_yasg生成可视化API文档，并提供一个简单的使用例子。

首先，确保您已经在您的Django项目中安装了drf_yasg。您可以使用以下命令安装：

pip install drf-yasg

接下来，打开您的Django项目的settings.py文件，并在INSTALLED_APPS中添加以下内容：

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

然后，我们需要在项目的根目录下创建一个名为swagger的文件夹，并在其中创建一个名为swagger.py的文件，并添加以下内容：

from drf_yasg import openapi
from drf_yasg.views import get_schema_view
from rest_framework.permissions import AllowAny

schema_view = get_schema_view(
    openapi.Info(
        title="API文档",
        default_version='v1',
        description="这是一个API文档示例",
    ),
    public=True,
    permission_classes=(AllowAny,),
)

我们还需要在urls.py文件中添加以下内容：

from django.urls import path
from .swagger import schema_view

urlpatterns = [
    ...
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    ...
]

现在，您可以使用以下命令运行您的Django项目：

python manage.py runserver

在浏览器中，访问http://localhost:8000/swagger/，您将看到使用drf_yasg生成的可视化API文档。

使用例子

为了演示如何在文档中添加使用例子，我们将创建一个简单的WebAPI来执行两个数字的加法。在您的Django项目的某个app中，创建一个名为views.py的文件，并添加以下代码：

from rest_framework.views import APIView
from rest_framework.response import Response

class AddNumbers(APIView):
    def post(self, request):
        num1 = request.data['num1']
        num2 = request.data['num2']
        result = num1 + num2
        return Response({'result': result})

然后，更新该app的urls.py文件，以便将AddNumbers视图映射到一个URL：

from django.urls import path
from .views import AddNumbers

urlpatterns = [
    ...
    path('add/', AddNumbers.as_view(), name='add'),
    ...
]

现在，打开您的浏览器并访问http://localhost:8000/swagger/，您将在API文档中看到一个名为/add/的端点。单击该端点，您将看到一个用于发送POST请求的按钮。

点击"Try it out"按钮，然后在输入框中输入两个数字，例如num1=5和num2=10。然后，单击"Execute"按钮。

您将在下方的"Response body"部分看到一个名为result的键和对应的值15，这是将输入的数字相加得到的结果。

这就是使用drf_yasg生成可视化API文档并添加使用例子的基本步骤。您可以扩展该文档，添加更多的端点和示例，以满足您的需求。希望这篇文章对您有所帮助！