DRF 自動生成介面文件

HammerZe發表於2022-04-08

目錄

DRF 自動生成介面文件

我們知道前後端分離，前端一般按後端寫好的介面去開發，那麼就需要我們明細後端介面資料等，需要寫介面文件，前端按照介面文件去開發

介面文件如何去寫？

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

  2. 第三方平臺錄入資料，固定的位置填固定的東西

    1. EOLINKER（推薦）可以協作，介面簡潔
地址：https://www.eolinker.com/#/?status=link-jump
2.RAP（前阿里媽媽團隊）支援版本管理，開源，有文件
地址：http://rap2.taobao.org/
3.EasyAPI  （相對來說easy）
地址：https://www.easyapi.com/
4.apizza
地址：https://apizza.net/pro/#/
5.showdoc
地址：https://www.showdoc.cc/
6.胖胖羊
地址：http://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/，即可看到自動生成的介面文件。

image

兩點說明：

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傳輸的資料往往都需要序列化，大部分資料型別都是字串。一些特殊的型別，例如列舉型別的字串，可以在說明裡描述。

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

舉個例子?：

名稱 是否必須 說明
userType 是 使用者型別。commom表示普通使用者，vip表示vip使用者
age 否 使用者年齡
gender 否 使用者性別。1表示男，0表示女

請求示例

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

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

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

異常處理

異常處理最小資料集

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

舉個例子?：

狀態碼 說明 解決方案
401 使用者名稱密碼錯誤 檢查使用者名稱密碼是否正確
424 超過最大線上數量 請在控制檯修改最大線上數量

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

如何組織？

一個建立使用者的例子：建立使用者

1 請求示例

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

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

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

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

名稱 是否必須 說明
userType 是 使用者型別。commom表示普通使用者，vip表示vip使用者
token 是 認證令牌

3 請求體引數模型

名稱 是否必須 說明
name 是 使用者名稱。4-50個字元
age 否 年齡
like 否 愛好。最多20個

4 響應體引數模型

名稱 說明
id 使用者id

5 異常處理

狀態碼 說明 解決方案
401 token過期 請重新申請token
424 超過最大在建立人數 請在控制檯修改最大建立人數

這樣組織的原因

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

文件提供的形式

文件建議由一下兩種形式，線上文件，pdf文件。

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

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

  • word文件
  • markdown文件

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

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

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

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

相關文章