接口文檔

接口編寫(xiě)已經(jīng)寫(xiě)完了,需要編寫(xiě)接口文檔，給前端的人使用

創(chuàng)新互聯(lián)公司專(zhuān)注于網(wǎng)站建設(shè)，為客戶(hù)提供成都網(wǎng)站設(shè)計(jì)、網(wǎng)站建設(shè)、網(wǎng)頁(yè)設(shè)計(jì)開(kāi)發(fā)服務(wù)，多年建網(wǎng)站服務(wù)經(jīng)驗(yàn)，各類(lèi)網(wǎng)站都可以開(kāi)發(fā)，高端網(wǎng)站設(shè)計(jì)，公司官網(wǎng)，公司展示網(wǎng)站，網(wǎng)站設(shè)計(jì)，建網(wǎng)站費(fèi)用，建網(wǎng)站多少錢(qián)，價(jià)格優(yōu)惠，收費(fèi)合理。

-請(qǐng)求地址
-請(qǐng)求方式
-支持的編碼格式
-請(qǐng)求參數(shù)(get,post參數(shù))
-返回格式示例

在公司的寫(xiě)法

1）直接使用word或者md寫(xiě)
2）使用接口文檔平臺(tái)，在接口文檔平臺(tái)錄入(Yapi（百度開(kāi)源的自己搭建）,第三方平臺(tái)(收費(fèi))，自己開(kāi)發(fā)接口文檔平臺(tái))

-https://www.showdoc.com.cn/item/index
- 不想花錢(qián)，沒(méi)有能力開(kāi)發(fā)，就使用開(kāi)源的YAPI，   https://zhuanlan.zhihu.com/p/

3）項(xiàng)目自動(dòng)生成：swagger，coreapi

-1 下載：pip3 install coreapi
-2 路由中配置：
        from rest_framework.documentation import include_docs_urls
        urlpatterns = [
            path('docs/', include_docs_urls(title='站點(diǎn)頁(yè)面標(biāo)題'))
        ]
-3 在視圖類(lèi)中加注釋
-4 在配置文件中配置
        REST_FRAMEWORK = {
         'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
        }

自動(dòng)生成接口文檔

REST framework可以自動(dòng)幫助我們生成接口文檔。
接口文檔以網(wǎng)頁(yè)的方式呈現(xiàn)。
自動(dòng)接口文檔能生成的是繼承自APIView及其子類(lèi)的視圖

安裝依賴(lài)

REST framewrok生成接口文檔需要coreapi庫(kù)的支持。

pip install coreapi

設(shè)置接口文檔

在總路由中添加接口文檔路徑(注意在總路由中配)。
文檔路由對(duì)應(yīng)的視圖配置為rest_framework.documentation.include_docs_urls，
參數(shù)title為接口文檔網(wǎng)站的標(biāo)題。

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='站點(diǎn)頁(yè)面標(biāo)題'))
]
注意：新版本還需要在setting里的REST_FRAMEWORK里添加以下配置，否則會(huì)包‘get_link’這樣字樣的錯(cuò)誤

'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',

文檔描述說(shuō)明的定義位置

單一方法的視圖，可以直接使用類(lèi)視圖的文檔字符串

class BookListView(generics.ListAPIView):
    """
    返回所有圖書(shū)信息.
    """

包含多個(gè)方法的視圖，在類(lèi)視圖的文檔字符串中，分開(kāi)方法定義

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有圖書(shū)信息.

    post:
    新建圖書(shū).
    """

對(duì)于視圖集ViewSet，仍在類(lèi)視圖的文檔字符串中封開(kāi)定義，但是應(yīng)使用action名稱(chēng)區(qū)分

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

    retrieve:
    返回圖書(shū)詳情數(shù)據(jù)

    latest:
    返回最新的圖書(shū)數(shù)據(jù)

    read:
    修改圖書(shū)的閱讀量
    """

訪問(wèn)接口文檔網(wǎng)頁(yè)

瀏覽器訪問(wèn) 127.0.0.1:8000/docs/，即可看到自動(dòng)生成的接口文檔。

注意要點(diǎn)

1） 視圖集ViewSet中的retrieve名稱(chēng)，在接口文檔網(wǎng)站中叫做read
2）參數(shù)的Description需要在模型類(lèi)或序列化器類(lèi)的字段中以help_text選項(xiàng)定義

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': '年齡'
            }
        }