DRF 自動生成接口文檔 coreapi和drf-yasg

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'),
]