Django DRF 自动生成接口文档

文章目录

1. 引子
2. 自动生成接口文档
3. 文档描述说明的定义位置

1. 引子

前端请求的url由谁来写

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

接口文档主要由谁来写

接口文档主要由后台开发者来设计修改。前端开发者起到了辅助的作用;
因为直接跟数据打交道的就是后台，后台是最清楚，数据库里面有什么数据,能返回什么数据
前端只是接口文档的使用者，使用过程中，发现返回的数据不对，则需要跟后台进行商量，由后台来修改;
前端不要随意更改接口文档，除非在取得后台开发人员的同意的情况下;

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

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

接口文档例子

2. 自动生成接口文档

编写接口文档的方式：

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

自动生成流程：

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

pip3 install coreapi

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

总路由

from rest_framework.documentation import include_docs_urlsurlpatterns = [...path('docs/', include_docs_urls(title='站点页面标题')),
]

配置文件

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

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

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

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

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

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

对于视图集 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 = Studentfields = "__all__"extra_kwargs = {'age': {'required': True,'help_text': '年龄'}}

Django DRF 自动生成接口文档相关推荐

DRF 自动生成接口文档
Python微信订餐小程序课程视频 https://edu.csdn.net/course/detail/36074 Python实战量化交易理财系统 https://edu.csdn.net/cou ...
Django框架深入了解_05 (Django中的缓存、Django解决跨域流程(非简单请求，简单请求)、自动生成接口文档)(二)
二.跨域: 回到顶部跨域知识介绍: 点我以前博客跨域解决方法:CORS:跨域资源共享 CORS请求分类(简单请求和非简单请求) 简单请求(simple request):只需要在头信息之中增加一个 ...
Django框架深入了解_05 (Django中的缓存、Django解决跨域流程(非简单请求，简单请求)、自动生成接口文档)(一)
阅读目录一.Django中的缓存: 前戏: Django中的几种缓存方式: Django中的缓存应用: 二.跨域: 跨域知识介绍: CORS请求分类(简单请求和非简单请求) 示例: 三.自动生成接口 ...
DRF自动生成OpenAPI文档
DRF自动生成OpenAPI文档 API schemas是非常有用的,可以帮助我们生成接口文档以及可与API交互的动态客户端.Django REST Framework支持自动生成OpenAPI sc ...
Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
idea swagger生成接口文档_Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据...
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
java自动生成接口文档
java自动生成接口文档 maven依赖工具类展示效果首页接口页在平时的开发过程中必定要写接口文档作为程序员最烦的2件事 1.别人让你写接口文档 2.接手别人的项目没有接口文档由此可见 ...
SpringBoot自动生成接口文档
跟大家介绍一个自动生成接口文档的工具包,作者的理念是注释即文档,在写代码的时候写上注释,项目启动后就会生成接口文档,非常方便,省去了Swagger写注解的过程. 仓库地址:https://github ...
自动生成接口文档之JApiDocs教程
JApiDocs教程前言作为一名优秀的程序员来说,由于涉及到要与前端进行对接,所以避免不了的就是写接口文档.写完接口文档,一旦代码返回结果,参数等出现变动,接口文档还得随之改动,十分麻烦,违背了我 ...