REST framework可以自動幫助我們生成接口文檔。
接口文檔以網頁的方式呈現。
自動接口文檔能生成的是繼承自APIView及其子類的視圖。
1. 安裝依賴
REST framewrok生成接口文檔需要coreapi庫的支持。
pip install coreapi
2. 設置接口文檔訪問路徑
在總路由中添加接口文檔路徑。
文檔路由對應的視圖配置為rest_framework.documentation.include_docs_urls，
參數title為接口文檔網站的標題。
from rest_framework.documentation import include_docs_urls
urlpatterns = [
...
url(r'^docs/', include_docs_urls(title='My API title'))
]
3. 文檔描述說明的定義位置
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:
修改圖書的閱讀量
"""
4. 訪問接口文檔網頁
瀏覽器訪問 127.0.0.1:8000/docs/，即可看到自動生成的接口文檔。
兩點說明：
1） 視圖集ViewSet中的retrieve名稱，在接口文檔網站中叫做read
2）參數的Description需要在模型類或序列化器類的字段中以help_text選項定義，如：
class BookInfo(models.Model):
...
bread = models.IntegerField(default=0, verbose_name='閱讀量', help_text='閱讀量')
...
或
class BookReadSerializer(serializers.ModelSerializer):
class Meta:
model = BookInfo
fields = ('bread', )
extra_kwargs = {
'bread': {
'required': True,
'help_text': '閱讀量'
}
}
第二種接口文檔
drf-yasg
# 安裝
pip install drf-yasg
# 添加到
INSTALLED_APPS = [
'drf_yasg',
]
from drf_yasg.views import get_schema_view
from drf_yasg import openapi
schema_view = get_schema_view(
openapi.Info(
title="接口文檔平台", # 必傳
default_version='v1', # 必傳
description="文檔描述",
terms_of_service='',
contact=openapi.Contact(email="1093254791@qq.com"),
license=openapi.License(name="BSD LICENSE")
),
public=True,
# permission_classes=(permissions.) # 權限類
)
urlpatterns += [
# re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0)),
path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger'),
path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),
]
