內容概要
- 寫接口文檔的四種方式
- DRF 自動生成接口文檔步驟（coreapi）
- 接口文檔組成
內容詳細
寫接口文檔的四種方式
目前流行的前后端分離模式，在前后端進行數據交互之前，后端需要把數據交互的接口的作用、地址、格式等信息提供給前端，需要我們書寫標准的接口文檔，以便與前端進行數據交互。
-
使用word或者md文檔編寫，自己純手寫
-
第三方平台錄入數據，固定的位置填固定的東西
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 -
公司自己開發接口平台，搭建接口平台
-
自動生成接口文檔：coreapi，swagger
也可以直接把 postman 的測試接口集合導出成文件，發送給前端
參考接口文檔：
- https://open.weibo.com/wiki/2/users/show
- https://www.cnblogs.com/noteaddr/p/12971759.html
- https://zhuanlan.zhihu.com/p/366025001
DRF 自動生成接口文檔步驟（coreapi）
1、安裝coreapi ：pip3 install coreapi
2、書寫路由：
參數title為接口文檔網站的標題
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
path('docs/', include_docs_urls(title='站點頁面標題'))
]
3、寫好視圖層類
4、項目下的配置文件 settings.py 配置 ：
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'
5、訪問地址： http://127.0.0.1:8000/docs/
6、給前端，前端按照這個接口文檔開發
7、基於這個，錄入到第三方接口平台，自己寫word文檔
文檔描述說明的定義位置#
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:
修改圖書的閱讀量
"""
寫視圖類，只需要加注釋即可
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': '年齡'
}
}
接口文檔組成
1 HTTP攜帶信息的方式
- url
- headers
- body: 包括請求體，響應體
2 分離通用信息
一般來說，headers里的信息都是通用的，可以提前說明，作為默認參數
3 路徑中的參數表達式
URL中參數表達式使用mustache的形式，參數包裹在雙大括號之中``
例如：
/api/user//api/user/?age=&gender=
4 數據模型定義
數據模型定義包括：
- 路徑與查詢字符串參數模型
- 請求體參數模型
- 響應體參數模型
數據模型的最小數據集：
- 名稱
- 是否必須
- 說明
“最小數據集”（MDS）是指通過收集最少的數據，較好地掌握一個研究對象所具有的特點或一件事情、一份工作所處的狀態，其核心是針對被觀察的對象建立起一套精簡實用的數據指標。最小數據集的概念起源於美國的醫療領域。最小數據集的產生源於信息交換的需要，就好比上下級質量技術監督部門之間、企業與質量技術監督部門之間、質量技術監督部門與社會公眾之間都存在着信息交換的需求。
一些文檔里可能會加入字段的類型，但是我認為這是沒必要的。以為HTTP傳輸的數據往往都需要序列化，大部分數據類型都是字符串。一些特殊的類型，例如枚舉類型的字符串，可以在說明里描述。
另外：數據模型非常建議使用表格來表現。
舉個栗子?：
| 名稱 | 是否必須 | 說明 |
|---|---|---|
| userType | 是 | 用戶類型。commom表示普通用戶，vip表示vip用戶 |
| age | 否 | 用戶年齡 |
| gender | 否 | 用戶性別。1表示男，0表示女 |
5 請求示例
// general
POST http://www.testapi.com/api/user
// request payload
{
"name": "qianxun",
"age": 14,
"like": ["music", "reading"],
"userType": "vip"
}
// response
{
"id": "asdkfjalsdkf"
}
6 異常處理
異常處理最小數據集
- 狀態碼
- 說明
- 解決方案
舉個栗子?：
| 狀態碼 | 說明 | 解決方案 |
|---|---|---|
| 401 | 用戶名密碼錯誤 | 檢查用戶名密碼是否正確 |
| 424 | 超過最大在線數量 | 請在控制台修改最大在線數量 |
之前我一直不想把解決方案加入異常處理的最小數據集，但是對於很多開發者來說，即使它知道424代表超過最大在線數量。如果你不告訴如果解決這個問題，那么他們可能就會直接來問你。所以最好能夠一步到位，直接告訴他應該如何解決，這樣省時省力。
7 如何組織？
7.1 一個創建用戶的例子：創建用戶
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 | 超過最大在創建人數 | 請在控制台修改最大創建人數 |
7.2 這樣組織的原因
請求示例: 請求示例放在第一位的原因是，要用最快的方式告訴開發者，這個接口應該如何請求路徑與查詢字符串參數模型： 使用mustache包裹參數請求體參數模型：如果沒有請求體，可以不寫響應體參數模型：異常處理
8 文檔提供的形式
文檔建議由一下兩種形式，在線文檔，pdf文檔。
-
在線文檔- 更新方便
- 易於隨時閱讀
- 易於查找
-
pdf文檔- 內容表現始終如一，不依賴文檔閱讀器
- 文檔只讀，不會被輕易修改
其中由於是面對第三方開發者，公開的在線文檔必須提供；由於某些特殊的原因，可能需要提供文件形式的文檔，建議提供pdf文檔。當然，以下的文檔形式是非常不建議提供的：
- word文檔
- markdown文檔
word文檔和markdown文檔有以下缺點：
文檔的表現形式非常依賴文檔查看器：各個版本的word文檔對word的表現形式差異很大，可能在你的電腦上內容表現很好的文檔，到別人的電腦上就會一團亂麻；另外markdown文件也是如此。而且markdown中引入文件只能依靠圖片鏈接，如果文檔中含有圖片，很可能會出現圖片丟失的情況。文檔無法只讀：文檔無法只讀，就有可能會被第三方開發者在不經意間修改，那么文檔就無法保證其准確性了。
總結一下，文檔形式的要點：
只讀性：保證文檔不會被開發者輕易修改一致性：保證文檔在不同設備，不同文檔查看器上內容表現始終如一易於版本管理：文檔即軟件（DAAS: Document as a Software），一般意義上說軟件 = 數據 + 算法, 但是我認為文檔也是一種組成軟件的重要形式。既然軟件需要版本管理，文檔的版本管理也是比不可少的。