生成項目依賴包文檔、自動生成接口文檔

一. 生成項目依賴包文檔的兩種方式

1.1 pipreqs模塊

　　項目中一般會安裝不少模塊，爲了移植性更好，咱們可使用pipreqs模塊生成依賴包文檔。

　　1.1 安裝pipreqs模塊

pip install pipreqs

　　1.2 生成對應項目的路徑

　　切換至項目根目錄，或者是給一個項目的路徑：

 D:\youkutest\luffyapi>pipreqs ./ --encoding=utf8

　　上面項目名爲luffyapi，後面加--encoding=utf8是防止由於編碼問題報錯，建議加上。

　　1.3 新環境中安裝依賴包

　　將整個項目複製至新環境時，只需執行如下命令便可安裝依賴包，在此以前先在新環境中安裝pipreqs。

pip install -r requriements.txt

 　　注意：該模塊有時候沒法生成全部依賴包，部分可能須要本身手動裝的。

1.2 pip freeze

　　freeze是pip自帶的生成依賴包的方法，推薦使用該方式，無需安裝其餘模塊。不過該方法也沒法生成全部依賴包，好比經過http安裝的xadmin等，通常這些模塊能夠運行項目時根據報錯的模塊信息安裝便可。

# 好比能夠寫pip freeze > requirement.txt
pip freeze > 保存時的文件名.格式 

# 安裝生成的依賴包，如pip install -r requirement.txt
pip install -r 文件名.格式

 

二. coreapi自動生成接口文檔

　　工做中接口文檔的撰寫如何手寫很費時，djangorestframework爲咱們提供了自動生成接口文檔的方法，不過該方法只會生成直接或間接繼承APIView類的視圖的接口文檔。

　　2.1 安裝依賴包

pip install -i https://pypi.douban.com/simple/ coreapi

　　2.2 設置接口文檔訪問路徑

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

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

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

from rest_framework.documentation import include_docs_urls

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

 　　2.3 文檔描述說明的定義位置

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

class BookListView(generics.ListAPIView):
    """
    返回全部圖書信息.
    """

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

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

    post:
    新建圖書.
    """

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

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

    retrieve:
    返回圖書詳情數據

    latest:
    返回最新的圖書數據

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

　　2.4 訪問接口文檔網頁

　　瀏覽器訪問 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': '年齡'
            }
        }