[Django REST framework – 自動生成介面文檔、分頁]

[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 瀏覽的地址（瀏覽器中）
    //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中測試）   
    //127.0.0.1:8000/books/?page=3  # 查第3頁
    //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中測試）   
    //127.0.0.1:8000/books/  # 默認從0開始取2條
    //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中測試）   
    //127.0.0.1:8000/books/?cursor=cD0y   # 按照cursor給的key值查找下一頁
    //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

Tags:

VirMach 便宜 VPS

QNews

QNews