如何正確記錄查詢參數（搜索、過濾）Django Rest Framework？

Question

我是 DRF 渲染文檔的新手。 我無法理解如何在代碼中正確記錄它以在文檔中呈現描述。 我正在使用DRF Docs 。

例如：我有可以檢索一些數據的路線。 在相關的觀點我有：

search_fields = ('name', 'registration_date')

但是這些字段在文檔頁面沒有描述。 .

所以我想為他們添加一個描述。 有沒有辦法做到這一點？

Answer 1

基本上您正在尋找REST“架構”功能。 看這里： REST-SCHEMA

使用此工具，您可以慢慢地將描述添加到您希望的所有字段中。

這是一個很好的howto頁面： 教程7：模式和客戶端庫

Answer 2

概括

DRF 文檔中有三種類型的描述（我已經嘗試過），它們依賴於兩個位置的設置。

• 類型 1 ：路徑參數描述 -> 在模型字段定義中設置
• 類型 2 ：查詢參數描述 -> 在特定字段的過濾器定義中設置
• 類型 3 ：請求正文描述 -> 與類型 1 相同

類型 1 和類型 3 描述的模型字段定義

# my_project/my_app/models.py
from django.db import models
from django.utils.translation import gettext_lazy as _

class MyModel(models.Model):
    id = models.BigAutoField(primary_key=True, help_text=_("Field id - This will show up in DRF docs Path Parameter Description/Request Body Description, '_' meaning using django translation module"))
    field1 = models.IntegerField(help_text=_("Field field1 - This will show up in DRF docs Path Parameter Description/Request Body Description, '_' meaning using django translation module"))

SearchFilter 用於類型 2 描述的特定字段定義

# my_project/my_app/filters.py
from rest_framework import filters

class MyFilter(filters.SearchFilter):
    search_param = 'field1'
    search_title = 'Exact matches Field1' # Shows up in DRF docs interactive query pop-up menu as the title for the query section of the field1
    search_description = 'This will show up in DRF docs Query Parameter Description'

序列化程序和 ViewSet 配置

# my_project/my_app/serializers.py
from rest_framework import serializers

from my_app.models import MyModel

class MySerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = '__all__'

# my_project/my_app/views.py
from rest_framework import viewsets

from my_app.models import MyModel
from my_app.serializers import MySerializer
from my_app.filters import MyFilter

class MyViewSets(viewsets.ModelViewSet):
    queryset = MyModel.objects.all()
    serializer_class = MySerializer
    filter_backends = [MyFilter]
    search_fields = ['=field1', '@field1']
        # The first charactor '='/'^' is used by SearchFilter.filter_queryset while doing
        # the SearchFilter.construct_search method
        # and '=' for exact match while '^' for starts with search
        # One could get all options at rest_framework.filters.SearchFilter.lookup_prefixes
        # BTW my rest_framework version is djangorestframework==3.11.1

最后是網址和設置配置

# my_project/my_app/urls.py
from django.urls import path, include
from rest_framework import routers

from my_app.views import MyViewSets

router = routers.DefaultRouter()
router.register('test', MyViewSets)

urlpatterns = [
    path('', include(router.urls))
]

# my_project/my_project/urls.py
from django.urls import path, include
from rest_framework.documentation import include_docs_urls

urlpatterns = [
    path('docs/', include_docs_urls('API Documentaion')),
    path('my_app/', include('my_app.urls'))
]

演示在這里： drf_docs_description