如何自动生成带参数的django rest框架文档？

问题描述

我使用 redoc + drf_yasg 来生成我用 django-rest-framework 制作的 api 的文档。只要我添加一个入口点，它就会在文档中很好地显示出来。

但是，我不明白如何在文档中添加可以在查询过程中给出的搜索参数。

例如，在list函数中，我可以传递2个可选参数，一个id和一个名称：

class TechnicalDataViewSet(viewsets.ViewSet):
    """
    A simple ViewSet for listing or retrieving machine.
    """
    permission_classes = [permissions.IsAuthenticated]
    def list(self,request):
        id_machine = self.request.query_params.get('id_machine')
        name = self.request.query_params.get('name')
        queryset = TechnicalData.objects.all()
        if id_machine:
            queryset = queryset.filter(machine__id=id_machine)
        if name:
            queryset = queryset.filter(name=name)
        serializer = TechnicalDataSerializer(queryset,many=True)
        return Response(serializer.data)

    def retrieve(self,request,pk=None):
        queryset = TechnicalData.objects.all()
        technical_data = get_object_or_404(queryset,pk=pk)
        serializer = TechnicalDataSerializer(technical_data)
        return Response(serializer.data)

我在文档中没有看到任何提及参数的内容。我如何添加它们？

我不知道这是否有帮助，但这是我实现 redoc 的方式：

schema_view = get_schema_view( 
   openapi.Info( 
      title="test API",default_version='v1',description=f"""
        # Public API
        
        **Reserved to authenticated users**
        
        Token Lifetime :
        
        * ACCESS_TOKEN_LIFETIME : {duration(settings.SIMPLE_JWT.get('ACCESS_TOKEN_LIFETIME'))}
        * REFRESH_TOKEN_LIFETIME : {duration(settings.SIMPLE_JWT.get('REFRESH_TOKEN_LIFETIME'))}
        
        ### Links
        [Get access token](************)
        
        ### Format
        Use `?format=` option in url:
        * `?format=api` (default)
        * `?format=json`
      """,terms_of_service="",contact=openapi.Contact(email="***********"),),public=True,permission_classes=(permissions.AllowAny,) 

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

解决方法

如果您想提供有关参数的信息，则必须将参数添加到您的视图中。我使用带有 swagger 的 drf_yasg 但也许这可能会有所帮助。这是一个例子。

from drf_yasg import openapi
from drf_yasg.utils import swagger_auto_schema


class TechnicalDataViewSet(viewsets.ViewSet):
    """
    A simple ViewSet for listing or retrieving machine.
    """
    permission_classes = [permissions.IsAuthenticated]

    id_machine = openapi.Parameter('id_machine',openapi.IN_QUERY,type=openapi.TYPE_INTEGER,required=False)
    name = openapi.Parameter('account',type=openapi.TYPE_STRING,required=False)

    @swagger_auto_schema(manual_parameters=[id_machine,name])
    def list(self,request):
        id_machine = self.request.query_params.get('id_machine')
        name = self.request.query_params.get('name')
        queryset = TechnicalData.objects.all()
        if id_machine:
            queryset = queryset.filter(machine__id=id_machine)
        if name:
            queryset = queryset.filter(name=name)
        serializer = TechnicalDataSerializer(queryset,many=True)
        return Response(serializer.data)

    @swagger_auto_schema(manual_parameters=[id_machine,name])
    def retrieve(self,request,pk=None):
        queryset = TechnicalData.objects.all()
        technical_data = get_object_or_404(queryset,pk=pk)
        serializer = TechnicalDataSerializer(technical_data)
        return Response(serializer.data)

django django django-rest-framework redoc