drf的接口文檔生成與管理

目錄

• 1、接口文檔簡述

• 2、Core API 生成接口文檔

• 2.1 安裝 Core API 庫

• 2.2 設置接口文檔訪問路徑

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

• 2.4 訪問查看

• 2.5 補充說明

• 3、Swagger 生成接口文檔

• 3.1 Swagger 介紹

• 3.2 安裝 django-rest-swagger 庫

• 3.3 配置 app 及 swagger

• 3.4 配置相關路由

• 3.5 訪問查看

• 3.6 說明

• 4、drf-yasg(Swagger 升級版)

• 4.1 drf-yasg 介紹

• 4.2 安裝 drf-yasg 庫

• 4.3 配置 app

• 4.4 配置路由 url

• 4.5 訪問查看

• 4.6 更多配置及說明

1、接口文檔簡述

在項目開發(fā)中，例如web項目的前后端分離開發(fā)，需要由前后端相關人員共同定義接口，編寫接口文檔。之后大家都根據這個接口文檔進行開發(fā)，到項目結束前都要一直維護。一個好的接口文檔能夠幫助我們快速上手這類項目、便于閱讀已有代碼、對接接口自動化測試等等

往往一個清晰的 API 接口文檔編寫起來比較費時費力，于是有很多接口文檔管理工具供我們使用：YApi、ShowDoc、DocWay，以及可直接利用接口測試生成接口文檔的工具Postman、Apipost......

上面列出的工具或多或少都需要花費一定時間去手動維護，在drf后端項目中可以利用其自帶的Core API、第三方庫Swagger以及更好的drf-yasg自動生成接口文檔

2、Core API 生成接口文檔

參考Core API 官網^[1]以及drf 官網^[2]，最終生成的接口文檔是以網頁的方式呈現的，自動接口文檔能生成的是繼承自APIView及其子類的視圖，具體實現流程如下

2.1 安裝 Core API 庫

pip3 install coreapi
pip3 freeze > requirements.txt

2.2 設置接口文檔訪問路徑

在配置文件settings.py中配置接口文檔

REST_FRAMEWORK = {
    ...
    # core api接口文檔
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
}

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

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

配置url主路由，其中參數title為接口文檔網站的標題

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='API document')),
]

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

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

class HostListView(generics.ListAPIView):
    """
    返回所有主機信息.
    """

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

class HostListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有主機信息.

    post:
    新建主機.
    """

• 對于視圖集ViewSet，仍在類視圖的文檔字符串中分開定義，但是應使用action對應的名稱進行區(qū)分

class HostInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回主機列表數據

    retrieve:
    返回主機詳情數據

    latest:
    返回最新的主機數據

    read:
    修改主機的訪問記錄
    """

2.4 訪問查看

按照上述規(guī)范優(yōu)化好后端接口的視圖后，重啟項目，訪問接口文檔

2.5 補充說明

1、上面訪問到的接口文檔，可以按照右邊的指引通過安裝coreapi-cli，通過命令行操作訪問接口文檔

2、對于視圖集ViewSet中的retrieve名稱，在接口文檔中叫做read

3、接口文檔中參數Description需要在模型類或序列化器類的字段中以help_text選項定義，例如

在模型類中定義

class EnvironmentView(models.Model):
    ...
    name = models.CharField(max_length=32, verbose_name='環(huán)境名稱', help_text='環(huán)境名稱')
    ...

在序列化器中定義

class EnvironmentModelSerializer(serializers.ModelSerializer):

    class Meta:
        model = Environment
        fields = "__all__"
        extra_kwargs = {
            'name': {
                'required': True,
                'help_text': '環(huán)境名稱'
            }
          ...
        }

3、Swagger 生成接口文檔

3.1 Swagger 介紹

Swagger^[3]是一個規(guī)范和完整的框架，用于生成、描述、調用和可視化RESTful風格的Web服務?？傮w目標是使客戶端和文件系統(tǒng)源代碼作為服務器以同樣的速度來更新。

當接口有變動時，對應的接口文檔也會自動更新

Swagger優(yōu)勢

• Swagger可生成一個具有互動性的API控制臺，可快速學習和嘗試API
• Swagger可生成客戶端SDK代碼，用于不同平臺上Java、Python...的實現
• Swagger文件可在許多不同的平臺上從代碼注釋中自動生成
• Swagger有一個強大的社區(qū)，里面有許多強悍的貢獻者

要提到的是，作為一個工具人，常用的httpbin模擬請求工具也是基于swagger的

下面記錄在drf中通過swagger生成接口文檔的具體實現流程，參考drf swagger 文檔^[4]

3.2 安裝 django-rest-swagger 庫

pip3 install django-rest-swagger
pip3 freeze > requirements.txt

3.3 配置 app 及 swagger

在配置文件settings.py中進行配置

配置app

INSTALLED_APPS = [
    ...
    'rest_framework',
    'rest_framework_swagger'
]

配置swagger

# swagger 配置項
SWAGGER_SETTINGS = {
    # 基礎樣式
    'SECURITY_DEFINITIONS': {
        "basic": {
            'type': 'basic'
        }
    },
    # 如果需要登錄才能夠查看接口文檔, 登錄的鏈接使用 restframework 自帶的.
    'LOGIN_URL': 'rest_framework:login',
    'LOGOUT_URL': 'rest_framework:logout',
    # 控制API列表的顯示方式 None 所有操作均已折疊 list 列出所有操作 full 擴展所有操作
    'DOC_EXPANSION': None,
    # 是否顯示請求標頭
    'SHOW_REQUEST_HEADERS': True,
    # 切換使用Django Auth作為身份驗證機制 將其設置為True將會在Swagger UI上顯示一個登錄/注銷按鈕，并將csrf_tokens發(fā)布到API
    'USE_SESSION_AUTH': True,
    # 接口文檔中方法列表以首字母升序排列
    'APIS_SORTER': 'alpha',
    # 如果支持json提交, 則接口文檔中包含json輸入框
    'JSON_EDITOR': True,
    # 方法列表字母排序
    'OPERATIONS_SORTER': 'alpha',
    # 在線模式驗證器的URL 修改為指向本地安裝，或設置None為禁用
    'VALIDATOR_URL': None,
}

3.4 配置相關路由

由于上面開啟了訪問swagger需要登錄，因此需要在路由中開啟drf默認的登錄入口，修改主路由

from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer, OpenAPIRenderer
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])

urlpatterns = [
    # drf認證
    path(r'api-auth/', include('rest_framework.urls', namespace='rest_framework')),
    # swagger接口文檔
    path('docs/', schema_view, name='docs'),
    ...
]

3.5 訪問查看

完成后重啟項目，如果在此之前有進行數據庫同步并創(chuàng)建了用戶，那么就可以直接訪問接口文檔的url，并跳轉到drf的認證界面進行登錄

swagger界面給人以清爽簡約的感覺，通過展開接口還可以對接口（傳參）進行測試

3.6 說明

Django REST Swagger從19年開始就已棄用不再維護了，作者在官方網站上說明了更推薦使用drf-yasg

可以閱讀https://github.com/marcgibbons/django-rest-swagger查看更多相關說明

4、drf-yasg(Swagger 升級版)

4.1 drf-yasg 介紹

參考drf-yasg 官網^[5]，drf-yasg是基于Swagger和OpenAPI 2.0規(guī)范的API文檔自動化生成工具，能夠生成比原生swagger更為友好的API文檔界面

目前的兼容性如下

• Django Rest Framework: 3.10, 3.11, 3.12
• Django: 2.2, 3.0, 3.1
• Python: 3.6, 3.7, 3.8, 3.9

4.2 安裝 drf-yasg 庫

在操作下面的步驟前請將第 3 節(jié)swagger相關內容全部注釋或還原

pip3 install drf-yasg
pip3 freeze > requirements.txt

4.3 配置 app

INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_yasg'
]

4.4 配置路由 url

from rest_framework import permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
...

schema_view = get_schema_view(
    # 具體定義詳見 [Swagger/OpenAPI 規(guī)范](https://swagger.io/specification/#infoObject "Swagger/OpenAPI 規(guī)范")
    openapi.Info(
        title="Snippets API",
        default_version='v1',
        description="Test description",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="[email protected]"),
        license=openapi.License(name="BSD License"),
    ),
    # public 表示文檔完全公開, 無需針對用戶鑒權
    public=True,
    # 可以傳遞 drf 的 BasePermission
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
    # drf_yasg
    re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-spec'),
    re_path(r'^swagger/$', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    re_path(r'^redoc/$', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
    ...
]

drf-yasg會暴露4種默認路徑endpoint, 分別為:

• /swagger.json, JSON 格式的 API 定義
• /swagger.yaml, YAML 格式的 API 定義
• /swagger/, 基于原生 swagger-ui 樣式的前端頁面
• /redoc/, 基于 ReDoc 樣式的前端頁面

4.5 訪問查看

完成后重啟項目進行訪問

swagger

redoc

4.6 更多配置及說明

4.6.1 get_schema_view 的配置

函數 get_schema_view 的作用是返回自動生成 API 文檔的視圖類, 該函數接受以下參數:

• info: Swagger API Info對象, 具體定義詳見 Swagger/OpenAPI 規(guī)范^[6], 如果缺省, drf-yasg默認會用 DEFAULT_INFO 進行填充
• url: 項目 API 的基礎地址, 如果缺省, 則根據視圖所在的位置進行推導
• patterns: 自定義的urlpatterns, 該參數直接透傳至SchemaGenerator
• urlconf: 描述從哪個文件獲取路由配置, 缺省值是urls, 該參數直接透傳至SchemaGenerator
• public: 描述 API 文檔是否公開, 如果未 False, 則僅返回當前用戶具有權限的接口endpoints的API文檔
• validators: 用于校驗自動生成的Schema的校驗器, 目前僅支持 ssv 和 flex
• generator_class: 自定義OpenAPI schema生成器類, 該類應該繼承自 OpenAPISchemaGenerator
• authentication_classes: 用于schema view進行登錄認證的類
• permission_classes: 用于schema view進行權限校驗的類

4.6.2 SchemaView 的配置

通過函數get_schema_view可以獲取對應的SchemaView, 調用該類的with_ui或 without_ui方法可生成對應的視圖函數, 將其添加進urlpatterns即可訪問到自動生成的 API 文檔

• SchemaView.with_ui(renderer, cache_timeout, cache_kwargs): 返回使用指定UI渲染器的視圖函數, 可選的UI渲染器有: swagger, redoc。
• SchemaView.without_ui(cache_timeout, cache_kwargs): 返回無UI的視圖函數, 該函數可以返回json/yaml格式的swagger文檔

以上兩個函數均支持通過 cache_timeout 或 cache_kwargs 配置緩存參數

4.6.3 緩存的配置

由于schema通常在服務運行期間不會發(fā)生改變, 因此 drf-yasg使用django內置的 cache_page 實現開箱即用的緩存功能, 只需要配置對應的參數即可啟用, 對應參數解釋如下:

• cache_timeout: 用于指定緩存的生存時間
• cache_kwargs: 用于傳遞 cache_page 允許接受的非位置參數, 如 cache(指定 cache backend), key_prefix(緩存key的前綴) 等等, 詳見django官方文檔

需要注意的是, 由于 drf-yasg 支持針對不同用戶返回不一樣的 API 文檔(通過public、authentication_classes、permission_classes等參數配置), 因此對于不同用戶(通過 HTTP 請求頭中的 Cookie 和 Authorization 進行區(qū)分), 會在內存中分別進行緩存。

4.6.4 校驗文檔有效性

為保證自動生成文檔的有效性, 可以通過在get_schema_view中設置 validators 參數開啟校驗自動化生成文檔是否符合OpenAPI2.0規(guī)范的功能

4.6.5 代碼自動生成

使用Swagger/OpenAPI規(guī)范生成文檔的好處之一, 就是能通過API文檔自動生成不同語言的 SDK，該功能由swagger-codegen^[7]提供

see you ~

參考資料