Django DRF 自动生成接口文档

1. 引子

---

前端请求的url由谁来写

1. url 主要有后台来写，写完给前端；

2. 如果后台查询数据，需要借助查询条件才能查询前端需要的数据时后台会要求前端提供相关的的查询参数，这里查询的参数就是url请求的参数；参数前面用 ？连接 ， 几个参数中间 &号连接；

接口文档主要由谁来写

1. 接口文档主要由后台开发者来设计修改。前端开发者起到了辅助的作用;

2. 因为直接跟数据打交道的就是后台，后台是最清楚，数据库里面有什么数据,能返回什么数据

3. 前端只是接口文档的使用者，使用过程中，发现返回的数据不对，则需要跟后台进行商量，由后台来修改;

4. 前端不要随意更改接口文档，除非在取得后台开发人员的同意的情况下;

前端开发与后台交互的数据格式主要是什么

主要格式有四种：xml json form iframe，现在最常用的就是 json 格式

接口文档例子

2. 自动生成接口文档

编写接口文档的方式：

• 使用 word 、md 编写
• 使用接口文档平台编写，接口平台可以是现成的也可以是自己搭建的例如 yapi
• 自动生成接口文档，生成后可以导出到 yapi，REST framework 自动生成的接口文档是以网页的方式呈现

---

自动生成流程：

1. 安装依赖
   REST framewrok生成接口文档需要coreapi库的支持。

pip3 install coreapi

2. 设置接口文档访问路径
   在总路由中添加接口文档路径。
   文档路由对应的视图配置为rest_framework.documentation.include_docs_urls
   参数title为接口文档网站的标题。

总路由

from rest_framework.documentation import include_docs_urls

urlpatterns = [
	...
    path('docs/', include_docs_urls(title='站点页面标题')),
]

配置文件

REST_FRAMEWORK = {
	'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

3. 文档描述说明的定义位置

1. 单一方法的视图，可直接使用类视图的文档字符串，如下

class BookListView(generics.ListAPIView):
    """
    返回所有图书信息.
    """

2. 包含多个方法的视图，在类视图的文档字符串中，分开方法定义，如下

class BookListCreateView(generics.ListCreateAPIView):
    """
    get:返回所有图书信息
	post: 新建图书
    """

3. 对于视图集 ModelViewSet，仍在类视图的文档字符串中分开定义，但是应使用 action 名称区分，如下

class BookView(ModelViewSet):
    """
        list:返回全部图书信息
        retrieve:返回图书单一信息
        create:新建图书
        update:修改图书
        destroy:删除图书
    """

---

输入在总路由中定义的路由，访问的页面如下所示

---

两点说明：

1） 视图集 ViewSet 中的 retrieve 名称，在接口文档网站中叫做 read
2）参数的 Description 需要在模型类或序列化器类的字段中以 help_text 选项定义，如

class Student(models.Model):
    ...
    age = models.IntegerField(default=0, verbose_name='年龄', help_text='年龄')
    ...

或者

class StudentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Student
        fields = "__all__"
        extra_kwargs = {
            'age': {
                'required': True,
                'help_text': '年龄'
            }
        }