Django系列(1)-自動化生成API文檔

PS: 個人深感python開發者社區氛圍比安卓/ios/java差多了。不過，這也許是個機會～

前提: 本人開發環境是mac10.14.4，Python3.7.2

django-rest-swagger vs drf-yasg

百度google各種查詢帖子，python中生成自動化API文檔絕大部分用的都是django-rest-swagger庫，然而此庫作者表示在2019-06-04已停止更新，而且此庫需要的第三方版本庫是：

• Django 1.8+
• Django REST framework 3.5.1+
• Python 2.7, 3.5, 3.6
  換句話說，django-rest-swagger並不支持Python3.7的環境，所以本人選擇了drf-yasg庫，它需要的第三方版本庫是：
• Django Rest Framework: 3.8, 3.9
• Django: 1.11, 2.1, 2.2
• Python: 2.7, 3.5, 3.6, 3.7

drf-yasg快速上手

安裝

pip install -U drf-yasg

在settings.py聲明app,並將debug設置爲true

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

DEBUG = True

在根url.py添加scheme_view

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

schema_view = get_schema_view(
    openapi.Info(
        title="API文檔",
        default_version='v1.0.0',
        contact=openapi.Contact(name='聯繫開發者', email="your email"),
    ),
    permission_classes=(permissions.AllowAny,),
)

urlpatterns = [
   ...    
   url('swagger', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
]

踩坑

1. 找不到drf目錄下的靜態文件

解決方案：測試環境settings.py中的DEBUG設置爲true(方便生成api文檔), 生產環境設置爲False。在python環境中，如果使用drf庫生成API文檔，需要將DEBUG設置爲true，否則找不到靜態文件。

參考文檔

https://github.com/axnsan12/drf-yasg
https://github.com/marcgibbons/django-rest-swagger
https://drf-yasg.readthedocs.io/en/stable/settings.html#validator-url