安装

• coreapi (必须)
• Pygments (可选)
• Markdown (可选)

使用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/

image.png
image.png
演示二
http://127.0.0.1:8000/swagger/ image.png

演示三

image.png

以上三种第一种适合平台集成，第二种存在交互可以操作验证，第三种更加详细