RESTful自动生成文档

在前后端分离的项目中，在完成接口的开发之后，后端开发人员需要为前端人员编写接口文档，介绍接口调用方法和需要传递的参数。在 Django Rest framework 编写接口后，可以自动生成接口文档，这无疑减轻了不少工作量。

接口文档以网页的方式呈现，在生产接口文档前，需要做如下操作：

安装依赖
Django Rest framework 自动生成接口文档，需要coreapi库的支持，在终端输入如下命令：

pip install coreapi

在设置文件中进行配置
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema'
}

配置接口文档访路由地址
在总路由中添加接口文档路径。

文档路由对应的视图配置为rest_framework.documentation.include_docs_urls，

参数title为接口文档网站的标题。

from rest_framework.documentation import include_docs_urls
urlpatterns = [
    ...
    path('docs/', include_docs_urls(title='接口文档'))
]

文档描述说明的定义位置
单一方法的视图，可直接使用类视图的文档字符串，如：
class StudentView(generics.ListAPIView):
    """
    返回所有学生信息.
    """
包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如：
class StudentListCreateView(generics.ListCreateAPIView):
    """
    get:
    返回所有学生信息.
    post:
    新建学生信息.
    """
对于视图集 ViewSet，仍在类视图的文档字符串中分开定义，但是应使用操作动作名称来区分，如：
class BookInfoViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    返回学生列表数据
    retrieve:
    返回学生详情数据
    latest:
    返回最新的学生数据
    """