[Django REST framework - 自動生成介面文件、分頁]

劉較瘦丫發表於2021-07-07
DjangoRESTFramework

[Django REST framework - 自動生成介面文件、分頁]

自動生成介面文件

# 後端人員寫好介面，編寫介面文件，給前端人員看，前端人員依照介面文件開發

# 公司裡主流
	-後端，使用world，md寫，提到git上
    -公司有介面平臺，後端開發在介面平臺錄入（yapi，第三方），可以批量匯入
    -後端專案自動生成介面文件（不是特別美觀或友好，有時候還需要配合上面兩種）
    	-django的drf自動生成  coerapi，swagger：java，go，python

REST framework可以自動幫助我們生成介面文件。

介面文件以網頁的方式呈現。

自動介面文件能生成的是繼承自APIView及其子類的檢視。

介面文件 coreapi，swagger
​
安裝依賴：REST framewrok生成介面文件需要coreapi庫的支援。
    pip3 install coreapi
 
使用步驟：
​
1 在urls.py 路由中
    from rest_framework.documentation import include_docs_urls
​
    urlpatterns = [
     path('doc/', include_docs_urls(title='圖書管理專案介面文件')),
    ]
    
2 在settings.py 配置檔案中
    REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    }
    
3 在view.py 檢視類中對應的方法上加註釋即可
    
4 如果是ModelViewSet
   from app01 import models
    from app01 import serializer
    from rest_framework.viewsets import ModelViewSet
    from rest_framework.filters import OrderingFilter
​
class BookView(ModelViewSet):
    """
      list:
      返回圖書列表資料，通過Ordering欄位排序
​
      retrieve:
      返回圖書詳情資料
​
      latest:
      返回最新的圖書資料
​
      read:
      查詢單個圖書介面
    """
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    # 排序
    filter_backends = [OrderingFilter,]
    ordering_fields = ['price','name']
    
    
5 欄位描述，寫在models.py的help_text上
from django.db import models
​
class Book(models.Model):
    name = models.CharField(max_length=34,help_text='名字欄位，字串')
    price = models.IntegerField(help_text='價格欄位，整型')
​
6 瀏覽的地址（瀏覽器中）
    http://127.0.0.1:8000/doc/
            
# 如果繼承的是其它檢視類，直接在對應的def函式下面寫註釋即可，例：
class BookView(APIView):
    def get(self, request):
        """
        所有圖書資訊
        :param request: 
        :return: 
        """
        res = models.Book.objects.all()
        ser = serializer.BookModelSerializer(instance=res, many=True)
        return Response(ser.data)

img

分頁Pagination

REST framework提供了分頁的支援。可選分頁器有三種

三種分頁方式

1 三種分頁方式
 -基本分頁：PageNumberPagination
    page_size = 2  # 每頁顯示兩條
    page_query_param = 'page'  #查詢第幾頁的引數 ?page=3
    max_page_size = 4     #每頁最大顯示多少條
    page_size_query_param = 'size' #每頁顯示的條數查詢條件（預設是page_size顯示的條數） # ?page=3&size=3
    
    
 -偏移分頁：LimitOffsetPagination
    default_limit=2  #預設顯示幾條
    limit_query_param='limit'   # ？limit=3   表示取3條
    offset_query_param = 'offset' #偏移  ?offset=5&limit=3    #從第5個位置開始，取3條資料
    max_limit = 5   #最多顯示5條
    
    
 -遊標分頁：CursorPagination
    cursor_query_param = 'cursor' # 查詢的key值
    page_size = 2  # # 每頁顯示兩條
    ordering = 'id' # 按id欄位排序
    
    
2 如何使用
   - APP下建立一個自定義py檔案，eg：page.py
   - 在檔案中寫一個自定義分頁類，繼承三個之一，並重寫類屬性
   - 在檢視類中配置
    class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
             queryset = models.Book.objects.all()
         serializer_class = serializer.BookModelSerializer
         # 配置使用的分頁類
         pagination_class = CustomNumberPagination
        
    - 區域性使用
        pagination_class = CustomNumberPagination

    - 全域性使用，在配置檔案中（以後所有檢視的查詢所有方法都用這個分頁）
        REST_FRAMEWORK = {
     'DEFAULT_PAGINATION_CLASS':'app01.page.CustomNumberPagination'  
    }

基本分頁：PageNumberPagination

也是用的最多的一種
建立一個py檔案  # 任意名字  例如:page.py

1、在page.py 中自定義一個類，繼承PageNumberPagination，並重寫類屬性

from rest_framework.pagination import PageNumberPagination   # 匯入模組

class CustomNumberPagination(PageNumberPagination):  # 定義類名繼承父類  重寫屬性
    
    page_size = 2  # 每頁顯示兩條
    page_query_param = 'page'  #查詢第幾頁的引數 ?page=3

    max_page_size = 4     # 每頁最大顯示多少條
    page_size_query_param = 'size' #每頁顯示的條數查詢條件（預設是page_size顯示的條數） # ?page=2&size=3
    
    
2、在views.py 檢視類中配置 
from rest_framework.generics import ListAPIView, CreateAPIView
from rest_framework.viewsets import ViewSetMixin
from app01.page import CustomNumberPagination # 匯入自定義分頁類

class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    
    # 配置使用的分頁類
    pagination_class = CustomNumberPagination  # 自己定義的類名
    
4、請求方式：（postman中測試）   
    http://127.0.0.1:8000/books/?page=3  # 查第3頁
    http://127.0.0.1:8000/books/?page=2&size=3  # 第2頁顯示3條
    
    
3、區域性使用（檢視類中）
    pagination_class = CustomNumberPagination

4、全域性使用，在settings.py 配置檔案中（以後所有檢視的查詢所有方法都用這個分頁）
    REST_FRAMEWORK = {
 'DEFAULT_PAGINATION_CLASS':'app01.page.CustomNumberPagination'
}

img

偏移分頁：LimitOffsetPagination

用的比較少的一種
1、在page.py 中自定義一個分頁類，繼承LimitOffsetPagination，並重寫類屬性

from rest_framework.pagination import LimitOffsetPagination  # 匯入模組

class CustomLimitOffsetPagtion(LimitOffsetPagination):
    default_limit=2  # 預設顯示幾條
    limit_query_param='limit'   # ？limit=3   表示取3條
    offset_query_param = 'offset' #偏移  ?offset=5&limit=3   從第5個位置開始，取3條資料
    max_limit = 5   #最多顯示5條
	# 手動寫顯示10條  也是顯示5條 因為這已經寫死了 
    
2、在views.py 檢視類中配置 
from rest_framework.generics import ListAPIView, CreateAPIView
from rest_framework.viewsets import ViewSetMixin
from app01.page import CustomLimitOffsetPagtion # 匯入自定義偏移分頁類

class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    
    # 配置使用的分頁類
    pagination_class = CustomLimitOffsetPagtion
    
4、請求方式：（postman中測試）   
    http://127.0.0.1:8000/books/  # 預設從0開始取2條
    http://127.0.0.1:8000/books/?limit=3&offset=2  # 取3條，從第2條開始
    
3、區域性使用（檢視類中）
    pagination_class = CustomLimitOffsetPagtion

4、全域性使用，在settings.py 配置檔案中（以後所有檢視的查詢所有方法都用這個分頁）
    REST_FRAMEWORK = {
 'DEFAULT_PAGINATION_CLASS':'app01.page.CustomLimitOffsetPagtion'
}

img

遊標分頁：CursorPagination

基本不用，但針對千萬級別的資料，為了降低資料庫的壓力，建議使用這種
1、在page.py 中自定義一個分頁類，繼承CursorPagination，並重寫類屬性
## 優點：速度最快，資料量越大，越有優勢
## 缺點：只能前一頁和後一頁，不能直接跳到某一頁

from rest_framework.pagination import CursorPagination

class CustomCursorPagination(CursorPagination): # 查詢速度最快
    cursor_query_param = 'cursor' # 查詢的key值
    page_size = 2  #  每頁顯示兩條
    ordering = 'id' # 按id欄位排序  必須寫不然報錯
    
    # 下面兩個基本不用可配可不配
     page_size_query_param = 'size'   # 通過這個引數決定每頁顯示多少條 
  	 max_page_size = 5     # 每頁最大顯示多少條
    
2、在views.py 檢視類中配置 
from rest_framework.generics import ListAPIView, CreateAPIView
from rest_framework.viewsets import ViewSetMixin
from app01.page import CustomCursorPagination # 匯入自定義遊標分頁類

class BookView(ViewSetMixin,ListAPIView,CreateAPIView):
    queryset = models.Book.objects.all()
    serializer_class = serializer.BookModelSerializer
    # 配置使用的分頁類
    pagination_class = CustomCursorPagination
    
4、請求方式：（postman中測試）   
    http://127.0.0.1:8000/books/?cursor=cD0y   # 按照cursor給的key值查詢下一頁
    http://127.0.0.1:8000/books/?cursor=cj0xJnA9Mw%3D%3D  # 按照cursor給的key值查詢上一頁
    
3、區域性使用（檢視類中）
    pagination_class = CustomCursorPagination

4、全域性使用，在settings.py 配置檔案中（以後所有檢視的查詢所有方法都用這個分頁）
    REST_FRAMEWORK = {
 'DEFAULT_PAGINATION_CLASS':'app01.page.CustomCursorPagination'
}

繼承APIView實現三種分頁方式

class BookViewALL(APIView):   # 繼承APIView   需要自己寫路由

    def get(self,request,*args,**kwargs):
        book_list=Books.objects.all()
        #例項化得到一個物件
        pagination=CommonPageNumberPagination() # 只需要換此處的類就可以實現三種分頁的效果
        
        # 修改物件屬性，我們不需要改
        # pagination.page_query_param='page'

        #呼叫物件方法，傳入要分頁的資料，book_list,返回分頁號的資料
        book_list2=pagination.paginate_queryset(book_list,request,self)

        ser=BookSerializer(instance=book_list2,many=True)  # 序列化器
        # 自己寫返回格式
        res={'pre':pagination.get_previous_link(),'next':pagination.get_next_link(),'count':pagination.page.paginator.count,'data':ser.data}
        
        return Response(res)

        # 另一種返回方式 呼叫父類中的方法返回
        return pagination.get_paginated_response(ser.data)

img

相關文章