DRF 自動生成接口文檔

• 2022 年 4 月 8 日
• 筆記
• drf

DRF 自動生成接口文檔

我們知道前後端分離，前端一般按後端寫好的接口去開發，那麼就需要我們明細後端接口數據等，需要寫接口文檔，前端按照接口文檔去開發

接口文檔如何去寫？

1. 使用word或者md文檔編寫，自己純手寫

2. 第三方平台錄入數據，固定的位置填固定的東西

   1. EOLINKER（推薦）可以協作，界面簡潔
   地址：//www.eolinker.com/#/?status=link-jump
   2.RAP（前阿里媽媽團隊）支持版本管理，開源，有文檔
   地址：//rap2.taobao.org/
   3.EasyAPI  （相對來說easy）
   地址：//www.easyapi.com/
   4.apizza
   地址：//apizza.net/pro/#/
   5.showdoc
   地址：//www.showdoc.cc/
   6.胖胖羊
   地址：//doclever.cn/controller/console/console.html
   

3. 公司自己開發接口平台，搭建接口平台

4. 自動生成接口文檔：coreapi，swagger

​

自動生成接口文檔

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='站點頁面標題'))
]

文檔描述說明的定義位置

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:
    修改圖書的閱讀量
    """
    

寫視圖類，只需要加註釋即可

配置文件

REST_FRAMEWORK = {
 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
    # 新版drf schema_class默認用的是rest_framework.schemas.openapi.AutoSchema

}

# 不配置報錯：#AttributeError: 'AutoSchema' object has no attribute 'get_link'

訪問接口文檔網頁

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

如何寫好接口文檔

HTTP攜帶信息的方式

• url
• headers
• body: 包括請求體，響應體

分離通用信息

一般來說，headers里的信息都是通用的，可以提前說明，作為默認參數

路徑中的參數表達式

URL中參數表達式使用mustache的形式，參數包裹在雙大括號之中“

例如：

• /api/user/
• /api/user/?age=&gender=

數據模型定義

數據模型定義包括：

• 路徑與查詢字符串參數模型
• 請求體參數模型
• 響應體參數模型

數據模型的最小數據集：

• 名稱
• 是否必須
• 說明

「最小數據集」（MDS）是指通過收集最少的數據，較好地掌握一個研究對象所具有的特點或一件事情、一份工作所處的狀態，其核心是針對被觀察的對象建立起一套精簡實用的數據指標。最小數據集的概念起源於美國的醫療領域。最小數據集的產生源於信息交換的需要，就好比上下級質量技術監督部門之間、企業與質量技術監督部門之間、質量技術監督部門與社會公眾之間都存在着信息交換的需求。

一些文檔里可能會加入字段的類型，但是我認為這是沒必要的。以為HTTP傳輸的數據往往都需要序列化，大部分數據類型都是字符串。一些特殊的類型，例如枚舉類型的字符串，可以在說明裡描述。

另外：數據模型非常建議使用表格來表現。

舉個栗子?：

請求示例

// general 
POST //www.testapi.com/api/user

// request payload
{
    "name": "HammerZe",
    "age": 18,
    "like": ["music", "reading"],
    "userType": "vip"
}

// response
{
    "id": "asdkfjalsdkf"
}

異常處理

異常處理最小數據集

• 狀態碼
• 說明
• 解決方案

舉個栗子?：

之前我一直不想把解決方案加入異常處理的最小數據集，但是對於很多開發者來說，即使它知道424代表超過最大在線數量。如果你不告訴如果解決這個問題，那麼他們可能就會直接來問你。所以最好能夠一步到位，直接告訴他應該如何解決，這樣省時省力。

如何組織？

一個創建用戶的例子：創建用戶

1 請求示例

// general 
POST //www.testapi.com/api/user/vip/?token=abcdefg

// request payload
{
    "name": "qianxun",
    "age": 14,
    "like": ["music", "reading"]
}

// response
{
    "id": "asdkfjalsdkf"
}

2 路徑與查詢字符串參數模型
POST //www.testapi.com/api/user//?token=

3 請求體參數模型

4 響應體參數模型

5 異常處理

這樣組織的原因

1. 請求示例: 請求示例放在第一位的原因是，要用最快的方式告訴開發者，這個接口應該如何請求
2. 路徑與查詢字符串參數模型： 使用mustache包裹參數
3. 請求體參數模型：如果沒有請求體，可以不寫
4. 響應體參數模型
5. 異常處理

文檔提供的形式

文檔建議由一下兩種形式，在線文檔，pdf文檔。

• 在線文檔
  • 更新方便
  • 易於隨時閱讀
  • 易於查找
• PDF文檔
  • 內容表現始終如一，不依賴文檔閱讀器
  • 文檔只讀，不會被輕易修改

其中由於是面對第三方開發者，公開的在線文檔必須提供；由於某些特殊的原因，可能需要提供文件形式的文檔，建議提供pdf文檔。當然，以下的文檔形式是非常不建議提供的：

• word文檔
• markdown文檔

word文檔和markdown文檔有以下缺點：

• 文檔的表現形式非常依賴文檔查看器：各個版本的word文檔對word的表現形式差異很大，可能在你的電腦上內容表現很好的文檔，到別人的電腦上就會一團亂麻；另外markdown文件也是如此。而且markdown中引入文件只能依靠圖片鏈接，如果文檔中含有圖片，很可能會出現圖片丟失的情況。
• 文檔無法只讀：文檔無法只讀，就有可能會被第三方開發者在不經意間修改，那麼文檔就無法保證其準確性了。

總結一下，文檔形式的要點：

• 只讀性：保證文檔不會被開發者輕易修改
• 一致性：保證文檔在不同設備，不同文檔查看器上內容表現始終如一
• 易於版本管理：文檔即軟件（DAAS: Document as a Software），一般意義上說軟件 = 數據 + 算法, 但是我認為文檔也是一種組成軟件的重要形式。既然軟件需要版本管理，文檔的版本管理也是比不可少的。