使用drf_yasg.openapi为DjangoRestFramework项目自动生成中文API文档

在Django Rest Framework项目中，可以使用drf_yasg.openapi来自动生成中文API文档，并带有使用例子。drf_yasg是一个用于自动生成Swagger/OpenAPI规范的库。下面将介绍如何在Django Rest Framework项目中使用drf_yasg.openapi来生成中文API文档，并给出相应的例子。

首先，需要安装drf_yasg和django-filter库，可以使用pip命令进行安装。

pip install drf_yasg django-filter

接下来，在项目的settings.py文件中添加相关配置。

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

SWAGGER_SETTINGS = {
    'USE_SESSION_AUTH': False,
    'SECURITY_DEFINITIONS': {
        'apiKey': {
            'type': 'apiKey',
            'in': 'header',
            'name': 'Authorization'
        }
    },
}

然后，在项目的urls.py文件中引入drf_yasg的相关模块，注册接口。

from django.conf.urls import url
from django.urls import include
from rest_framework import routers
from drf_yasg import openapi
from drf_yasg.views import get_schema_view

router = routers.DefaultRouter()

# 注册接口
urlpatterns = [
    ...
    url(r'^api/', include(router.urls)),
    url(r'^api/docs/$', get_schema_view(
        openapi.Info(
            title="API文档",
            default_version='v1',
            description="这是一个API文档",
        ),
        public=True,
        permission_classes=(permissions.AllowAny,),
    ), name='swagger-ui'),
    ...
]

接着，在项目中的views.py文件中编写API接口的代码。以一个简单的User模型为例，创建一个UserViewSet类，并编写相应的API接口。

from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response

from .models import User
from .serializers import UserSerializer


class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    @action(detail=True, methods=['post'])
    def reset_password(self, request, pk=None):
        user = self.get_object()
        # 这里写重置密码的逻辑
        return Response({'msg': '密码重置成功'})

然后，在项目中的serializers.py文件中编写User模型的序列化器。

from rest_framework import serializers
from .models import User


class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = '__all__'

最后，在项目的examples.py文件中编写一些使用例子。

from drf_yasg import openapi

example_user = {
    'id': 1,
    'username': 'example',
    'password': '********',
    'email': 'example@example.com',
    'phone': '1234567890',
}

example_reset_password = {
    'msg': '密码重置成功',
}

example_user_response = openapi.Response(
    description='用户信息',
    schema=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'id': openapi.Schema(type=openapi.TYPE_INTEGER),
            'username': openapi.Schema(type=openapi.TYPE_STRING),
            'password': openapi.Schema(type=openapi.TYPE_STRING),
            'email': openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_EMAIL),
            'phone': openapi.Schema(type=openapi.TYPE_STRING),
        }
    )
)

example_reset_password_response = openapi.Response(
    description='重置密码响应',
    schema=openapi.Schema(
        type=openapi.TYPE_OBJECT,
        properties={
            'msg': openapi.Schema(type=openapi.TYPE_STRING),
        }
    )
)

现在就可以运行项目，并访问API文档了。打开浏览器，输入API文档的URL，例如 http://localhost:8000/api/docs/ ，就可以看到自动生成的API文档页面。

在API文档页面上可以看到接口的详细信息，包括请求方法、请求路径、请求参数、请求示例、响应参数、响应示例等等。同时，也会显示使用例子中定义的参数和响应示例。

通过使用drf_yasg.openapi，我们可以方便地在Django Rest Framework项目中自动生成中文API文档，并且提供了例子来帮助理解和使用API接口。这样不仅能够提高开发效率，还可以方便与前端工程师、测试工程师等对接接口。