如何使用drf_yasg.openapi在Python中生成中文接口文档示例

在Python中使用drf_yasg.openapi库来生成中文接口文档，你需要按照以下步骤进行操作:

1. 安装drf_yasg和openapi依赖库:

   pip install drf-yasg
   

2. 在你的Django项目的settings.py文件中添加drf_yasg到INSTALLED_APPS:

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

3. 创建一个新的Python文件，例如swagger.py，并编写以下代码:

   from drf_yasg import openapi
   from drf_yasg.views import get_schema_view
   from rest_framework.permissions import AllowAny
   from rest_framework import routers, serializers, viewsets
   from django.conf.urls import url, include

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

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

   router = routers.DefaultRouter()
   router.register('users', UserViewSet)

   schema_view = get_schema_view(
       openapi.Info(
           title="接口文档",
           default_version='v1',
           description="这是一个中文接口文档示例",
           terms_of_service="https://www.example.com/policies/terms/",
           contact=openapi.Contact(email="contact@example.com"),
           license=openapi.License(name="BSD License"),
       ),
       public=True,
       permission_classes=(AllowAny,),
   )

   urlpatterns = [
       url(r'^', include(router.urls)),
       url(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
       url(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
       url(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
   ]
   

4. 根据你的项目需要，修改schema_view的参数来自定义接口文档的信息，例如标题、版本、描述等。

5. 在你的项目的urls.py文件中导入swagger.py:

   import swagger
   

6. 添加swagger.urlpatterns到项目的urlpatterns:

   urlpatterns = [
       ...
       url(r'^api-docs/', include(swagger.urlpatterns)),
       ...
   ]
   

7. 运行你的Django应用程序，然后访问http://localhost:8000/api-docs/swagger/来查看生成的中文接口文档。

通过以上步骤，你就可以使用drf_yasg.openapi库在Python中生成中文接口文档了。

以下是一个使用User模型的使用例子，用于展示如何在接口文档中显示模型的字段信息。

假设你有以下User模型:

from django.db import models

class User(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField(max_length=100)

然后你可以在swagger.py文件中添加以下代码:

from drf_yasg import openapi

user_fields = {
    'name': openapi.Schema(type=openapi.TYPE_STRING, description='用户名'),
    'email': openapi.Schema(type=openapi.TYPE_STRING, format=openapi.FORMAT_EMAIL, description='邮箱')
}

class UserViewSet(viewsets.ModelViewSet):
    ...
    def get_view_description(self, html=False):
        return "用户接口"

    def get_view_model(self, view, request):
        return user_fields

    @swagger_auto_schema(manual_parameters=[
        openapi.Parameter('username', openapi.IN_QUERY, description='用户名', required=True, type=openapi.TYPE_STRING),
    ])
    def create(self, request, *args, **kwargs):
        super().create(request, *args, **kwargs)

通过get_view_model方法，我们可以为视图集的每个操作自定义字段的描述。在create方法中，我们使用了swagger_auto_schema装饰器来自定义一个URL参数。

这样，你就可以在接口文档中看到每个字段的描述以及自定义的URL参数了。记得运行应用程序并访问接口文档来查看效果。

希望这个示例可以帮助到你使用drf_yasg.openapi库在Python中生成中文接口文档。