drf之自動生成接口文檔

一 自動生成接口文檔

REST framework可以自動幫助我們生成接口文檔。

接口文檔以網頁的方式呈現。

自動接口文檔能生成的是繼承自APIView及其子類的視圖。

1.1. 安裝依賴

REST framewrok生成接口文檔需要coreapi庫的支持。

1	pip install coreapi

1.2. 設置接口文檔訪問路徑

在總路由中添加接口文檔路徑。

文檔路由對應的視圖配置為rest_framework.documentation.include_docs_urls，

參數title為接口文檔網站的標題。

1 2 3 4 5 6

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

1.3. 文檔描述說明的定義位置

1） 單一方法的視圖，可直接使用類視圖的文檔字符串，如

1 2 3 4

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

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

1 2 3 4 5 6 7 8

classBookListCreateView(generics.ListCreateAPIView): """ get: 返回所有圖書信息. post: 新建圖書. """

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14

classBookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet): """ list: 返回圖書列表數據 retrieve: 返回圖書詳情數據 latest: 返回最新的圖書數據 read: 修改圖書的閱讀量 """

1.4. 訪問接口文檔網頁

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

如果遇到報錯

1 2 3 4 5 6

#AttributeError: 'AutoSchema' object has no attribute 'get_link' REST_FRAMEWORK = { 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema', # 新版drf schema_class默認用的是rest_framework.schemas.openapi.AutoSchema }

兩點說明：

1） 視圖集ViewSet中的retrieve名稱，在接口文檔網站中叫做read

2）參數的Description需要在模型類或序列化器類的字段中以help_text選項定義，如：

1 2 3 4

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

或

1 2 3 4 5 6 7 8 9 10

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