drf介面文檔

介面文檔

介面編寫已經寫完了,需要編寫介面文檔，給前端的人使用

-請求地址
-請求方式
-支持的編碼格式
-請求參數(get,post參數)
-返回格式示例

在公司的寫法

1）直接使用word或者md寫
2）使用介面文檔平臺，在介面文檔平臺錄入(Yapi（百度開源的自己搭建）,第三方平臺(收費)，自己開發介面文檔平臺)

-https://www.showdoc.com.cn/item/index
- 不想花錢，沒有能力開發，就使用開源的YAPI，   https://zhuanlan.zhihu.com/p/366025001

3）項目自動生成：swagger，coreapi

-1 下載：pip3 install coreapi
-2 路由中配置：
        from rest_framework.documentation import include_docs_urls
        urlpatterns = [
            path('docs/', include_docs_urls(title='站點頁面標題'))
        ]
-3 在視圖類中加註釋
-4 在配置文件中配置
        REST_FRAMEWORK = {
         'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
        }

自動生成介面文檔

REST framework可以自動幫助我們生成介面文檔。
介面文檔以網頁的方式呈現。
自動介面文檔能生成的是繼承自APIView及其子類的視圖

安裝依賴

REST framewrok生成介面文檔需要coreapi庫的支持。

pip install coreapi

設置介面文檔

在總路由中添加介面文檔路徑。
文檔路由對應的視圖配置為rest_framework.documentation.include_docs_urls，
參數title為介面文檔網站的標題。

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='站點頁面標題'))
]

文檔描述說明的定義位置

單一方法的視圖，可以直接使用類視圖的文檔字元串

class BookListView(generics.ListAPIView):
    """
    返回所有圖書信息.
    """

包含多個方法的視圖，在類視圖的文檔字元串中，分開方法定義

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有圖書信息.

    post:
    新建圖書.
    """

對於視圖集ViewSet，仍在類視圖的文檔字元串中封開定義，但是應使用action名稱區分

class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回圖書列表數據

    retrieve:
    返回圖書詳情數據

    latest:
    返回最新的圖書數據

    read:
    修改圖書的閱讀量
    """

訪問介面文檔網頁

瀏覽器訪問 127.0.0.1:8000/docs/，即可看到自動生成的介面文檔。

註意要點

1） 視圖集ViewSet中的retrieve名稱，在介面文檔網站中叫做read
2）參數的Description需要在模型類或序列化器類的欄位中以help_text選項定義

class Student(models.Model):
    ...
    age = models.IntegerField(default=0, verbose_name='年齡', help_text='年齡')
    ...

或

class StudentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = "__all__"
        extra_kwargs = {
            'age': {
                'required': True,
                'help_text': '年齡'
            }
        }