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 更多配置及說明
    • 4.6.1 get_schema_view的配置
    • 4.6.2 SchemaView 的配置
    • 4.6.3 緩存的配置
    • 4.6.4 校驗文檔有效性
    • 4.6.5 代碼自動生成

1、接口文檔簡述

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

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

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

2、Core API生成接口文檔

參考Core API官網以及drf官網，最終生成的接口文檔是以網頁的方式呈現的，自動接口文檔能生成的是繼承自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對應的名稱進行區分

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

    retrieve:
    返回主機詳情數據

    latest:
    返回最新的主機數據

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

2.4 訪問查看

按照上述規范優化好后端接口的視圖后，重啟項目，訪問接口文檔

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='環境名稱', help_text='環境名稱')
    ...

在序列化器中定義

class EnvironmentModelSerializer(serializers.ModelSerializer):

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

3、Swagger生成接口文檔

3.1 Swagger介紹

Swagger是一個規范和完整的框架，用於生成、描述、調用和可視化RESTful風格的Web服務。總體目標是使客戶端和文件系統源代碼作為服務器以同樣的速度來更新。

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

Swagger優勢

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

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

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

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發布到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 訪問查看

完成后重啟項目，如果在此之前有進行數據庫同步並創建了用戶，那么就可以直接訪問接口文檔的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官網，drf-yasg是基於Swagger和OpenAPI 2.0規范的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節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 規范](https://swagger.io/specification/#infoObject)
    openapi.Info(
        title="Snippets API",
        default_version='v1',
        description="Test description",
        terms_of_service="https://www.google.com/policies/terms/",
        contact=openapi.Contact(email="[e-mail]"),
        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 規范, 如果缺省, 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通常在服務運行期間不會發生改變, 因此 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 進行區分), 會在內存中分別進行緩存。

4.6.4 校驗文檔有效性

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

4.6.5 代碼自動生成

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

see you ~

參考：

http://blog.shabbywu.cn/posts/2020/04/15/python-auto-doc-for-drf.html