DRF-自動生成接口文檔

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

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

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

1. 安裝依賴

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

pip install coreapi

 

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

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

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

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

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    url(r'^docs/', include_docs_urls(title='My REST API'))
]

 

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

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

class DepartmentListView(generics.ListAPIView):
    """
    返回所有部門信息.
    """

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

class DepartmentListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有部門信息.

    post:
    創建部門.
    """

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

class DepartmentViewSet(ListModelMixin, RetrieveModelMixin, GenericViewSet):
    """
    list:
    分頁查詢部門對象

    retrieve:
    查詢一個部門信息

    latest:
    查詢最新添加的部門

    name:
    修改部門名稱
    """

 

兩點說明：

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

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

class DepartmentSerializer(serializers.Serializer):
    ...
    name = serializers.CharField(label='部門名稱', max_length=20,
        help_text='部門名稱')
    ...

class DepartmentSerializer2(serializers.ModelSerializer):
    ...
    class Meta:
        ...
        extra_kwargs = {
            'name': {..., 'help_text': '部門名稱'}
        }