使用coreapi

最新版的DRF(>3.10)中, 需要添加如下配置

REST_FRAMEWORK = {

    # 指定用于支持coreapi的Schema
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',

}

项目中添加URL

from rest_framework.documentation import include_docs_urls
from django.urls import path, include

urlpatterns = [
    path('docs/', include_docs_urls(title='测试平台接口文档')),
]

演示：

image.png

image.png

添加注释

单一方法的视图
直接给视图类添加注释即可

class ProjectsListView(ListAPIView):
    """
    返回所有项目信息
    """

多个方法的视图

class ProjectsListCreateView(ListCreateAPIView):
    """
    get:
    返回所有项目信息

    post:
    新建项目
    """

视图集

class ProjectsViewset(viewsets.ModelViewSet):
    """
    create:
    创建项目

    retrieve:
    获取项目详情数据

    update:
    完整更新项目

    partial_update:
    部分更新项目

    destroy:
    删除项目

    list:
    获取项目列表数据
    
    names:
    获取所有项目名称

    interfaces:
    获取指定项目的所有接口数据
    """

添加注释后报告中就会显示描述

image.png

但是drf3.12之后就不会支持，推荐使用另一种

使用drf-yasg

安装

pip install drf-yasg

添加到INSTALLED_APPS中

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

在全局路由文件urls.py文件中添加配置

# 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="Lemon API接口文档平台",    # 必传
        default_version='v1',   # 必传
        description="这是一个美轮美奂的接口文档",
        terms_of_service="http://api.keyou.site",
        contact=openapi.Contact(email="keyou100@qq.com"),
        license=openapi.License(name="BSD License"),
    ),
    public=True,
    # permission_classes=(permissions.AllowAny,),   # 权限类
)


urlpatterns = [
    #三种不同风格的接口文档，自选其一
    re_path(r'^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),
    path('swagger/', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),
    path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),

]

验证一
http://127.0.0.1:8000/swagger/