Django+drf_yasg+rest_framework自动生成Swagger接口文档

修改setting文件

在Django注册drf_yasg、rest_framework，这样Django才能识别drf_yasg、rest_framework

INSTALLED_APPS = ['django.contrib.admin','django.contrib.auth','django.contrib.contenttypes','django.contrib.sessions','django.contrib.messages','django.contrib.staticfiles','oauth2_provider','corsheaders',# 需要添加的部分'rest_framework','rest_framework.authtoken','drf_yasg',###'staff', # 添加staff应用',]

配置swagger：

from django.urls import reverse_lazy
SWAGGER_SETTINGS = {'LOGIN_URL': reverse_lazy('admin:login'),'LOGOUT_URL': '/admin/logout','PERSIST_AUTH': True,'REFETCH_SCHEMA_WITH_AUTH': True,'REFETCH_SCHEMA_ON_LOGOUT': True,'DEFAULT_INFO': 'django_resfuls.urls.swagger_info',#此项配置必需要有，否则无法找到URL"DEFAULT_PAGINATOR_INSPECTORS": [# 'django_resfuls.inspectors.UnknownPaginatorInspector','drf_yasg.inspectors.DjangoRestResponsePagination','drf_yasg.inspectors.CoreAPICompatInspector',]
}

其中LOGIN_URL为登录URL，这里使用reverse_lazy生成。

路由设置

from django.contrib import admin
from django.urls import include, path, re_path
from rest_framework import permissions
from drf_yasg import openapi
from drf_yasg.views import get_schema_viewswagger_info = openapi.Info(title="Swagger-API接口文档",default_version='v1',description="""合同以及人员资料管理系统接口文档""",  # noqa# terms_of_service="https://www.google.com/policies/terms/",# contact=openapi.Contact(email="XXXXX@XXXXX.XXX"),license=openapi.License(name="***"),
)SchemaView = get_schema_view(validators=['ssv', 'flex'],public=True,permission_classes=[permissions.AllowAny],
)
# urlpatterns required for settings values
required_urlpatterns = [path('admin/', admin.site.urls),
]urlpatterns = [re_path(r'^cached/swagger(?P<format>.json|.yaml)$', SchemaView.without_ui(cache_timeout=None),name='cschema-json'),path('cached/swagger/', SchemaView.with_ui('swagger', cache_timeout=None), name='cschema-swagger-ui'),path('cached/redoc/', SchemaView.with_ui('redoc', cache_timeout=None), name='cschema-redoc'),# 人员path('cms/user/', include('staff.urls')),] + required_urlpatterns

生成的文档如图（URL：/cached/swagger/）：

接口文档生成

URL与视图的相互映射

本文接口视图全部都是类视图，这里列出两种类视图：
一是一个类视图对应多个URL；方法如下：
路由文件urls.py：

from django.urls import include, path
from staff import views
from rest_framework.routers import SimpleRouter
from rest_framework.response import Response
class StandardRouter(SimpleRouter):def __init__(self, trailing_slash='/?'):super(StandardRouter, self).__init__()self.trailing_slash = trailing_slashrouter = StandardRouter()
router.register('', views.StaffViewsSet)
urlpatterns = [# 人员资料管理path('', include(router.urls)),]

StandardRouter是实现让URL可以以’/'结尾，具体用法见：

路由配置
视图文件view.py

from django.http import JsonResponse
from rest_framework.decorators import action
from rest_framework import viewsetsfrom staff.models import TStaffInfo
from staff import serializers
from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi
class StaffViewsSet(viewsets.ViewSet):queryset = TStaffInfo.objects.all()def get_permissions(self):"""Instantiates and returns the list of permissions that this view requires."""permission_classes = []return [permission() for permission in permission_classes]# 员工信息列表页@swagger_auto_schema(request_body=serializers.ListRequestSerializer,responses={'200': serializers.ListResponsesSerializer,'400': "Bad Request"},# security=[],operation_id='列表页',operation_description='员工信息列表页',tags=['员工管理系统'],)@action(detail=False,methods=['post'],url_name='列表',url_path='list',)def list_(self, request):acc = serializers.StaffSerializer.data# staff = get_staff_list.Staffinfo()# result = staff.get_list_data(acc)return JsonResponse({"status": 200}, json_dumps_params={'ensure_ascii': False})# 员工信息详情页@swagger_auto_schema(request_body=openapi.Schema(type=openapi.TYPE_OBJECT,required=['id'],properties={'id': openapi.Schema(type=openapi.TYPE_INTEGER),},),# query_serializer=ListRequestSerializer,responses={'200': serializers.DetailRequestSerializer,'400': "Bad Request"},security=[],operation_id='详情页',operation_description='员信息详情页',tags=['员工管理系统'])@action(detail=False,methods=['post'],url_name='详情',url_path='detail',)def detail_(self, request):acc = request.dataprint('详情页请求数据', acc)# staff = get_staff_detail.StaffDetailInfo()# result = staff.get_detail_data(acc)return Response('')

该方法url的操作以及请求方法全部在action中，该类视图需要继承viewsets.ViewSet。
另外一种方式是一个URL对应一个类视图。
路由文件书写方式如图：

类视图文件：

他需要继承rest_framework.views中的APIView，即：

from rest_framework.views import APIView
class ContractList(APIView):...

序列化

swagger文档的作用是实现前后端开发人员的沟通桥梁，而沟通中最主要的是前端请求数据和后端相应数据的参数定义以及数据结构类型。在swagger_auto_schema中请求数据对应request_body，响应数据对应responses
其序列化文件serializers.py：

from decimal import Decimal
from django.contrib.auth import get_user_model
from django.core.validators import MinValueValidator
from rest_framework import serializersclass t_staff_certSerializer(serializers.Serializer):id = serializers.IntegerField(read_only=True,help_text="证书ID")staffId = serializers.IntegerField(read_only=True,help_text="员工ID")certType = serializers.IntegerField(read_only=True,help_text="证书类别：6大类")cert_id = serializers.IntegerField(read_only=True,help_text="证书对应数据字典的int值")certName = serializers.CharField(read_only=True,help_text="证书名称")certGrade = serializers.IntegerField(read_only=True,help_text="证书等级")certMajor = serializers.IntegerField(read_only=True,help_text="专业")certFulltime = serializers.IntegerField(read_only=True,help_text="是否是全日制；0->非全日制，1->全日制")certCode = serializers.CharField(read_only=True,help_text="证书编号")cert_state = serializers.IntegerField(read_only=True,help_text="证书状态")cert_person = serializers.CharField(read_only=True,help_text="证书获得者")cert_org = serializers.CharField(read_only=True,help_text="颁证机构")cert_issuer = serializers.CharField(read_only=True,help_text="签发人")cert_date = serializers.DateTimeField(read_only=True,help_text="颁证日期")valid_date = serializers.DateTimeField(read_only=True,help_text="有效日期")class t_staff_infoSerializer(serializers.Serializer):id = serializers.IntegerField(read_only=True,help_text="id")# created = UnixTimestampField(read_only=True)staffCode = serializers.CharField(help_text="员工编号",read_only=True,required=False, allow_blank=True)staffName = serializers.CharField(help_text="员工姓名", read_only=True,required=False, allow_blank=True)nation = serializers.CharField(read_only=True, help_text="国籍",required=False, allow_blank=True)bizGroup = serializers.CharField(read_only=True, help_text="事业群",required=False, allow_blank=True)bizDept = serializers.CharField(help_text="事业部", read_only=True,required=False, allow_blank=True)dept = serializers.CharField(help_text="部门", read_only=True,required=False, allow_blank=True)enrollDate = serializers.CharField(help_text="入职日期", read_only=True, required=False, allow_blank=True)graduateDate = serializers.CharField(help_text="毕业日期", read_only=True, required=False, allow_blank=True)workingDate = serializers.CharField(help_text="参加工作日期", read_only=True, required=False, allow_blank=True)birthday = serializers.CharField(help_text="出身年月日", read_only=True, required=False, allow_blank=True)idCardCode = serializers.CharField(help_text="身份证号", read_only=True, required=False, allow_blank=True)gender = serializers.IntegerField(help_text="性别")email = serializers.CharField(help_text="邮箱", read_only=True, required=False, allow_blank=True)college = serializers.CharField(help_text="毕业院校", read_only=True, required=False, allow_blank=True)major = serializers.CharField(help_text="专业", read_only=True, required=False, allow_blank=True)diploma = serializers.CharField(help_text="最高学历", read_only=True, required=False, allow_blank=True)diplomaCode = serializers.CharField(help_text="学历证号码", read_only=True, required=False, allow_blank=True)degree = serializers.CharField(help_text="最高学位", read_only=True, required=False, allow_blank=True)degreeCode = serializers.CharField(help_text="学位证编号", read_only=True, required=False, allow_blank=True)majorType = serializers.CharField(help_text="专业类别", read_only=True, required=False, allow_blank=True)contractUntil = serializers.DateField(help_text="合同到期日期")idCardUntil = serializers.DateField(help_text="身份证到期日期")certFulltime = serializers.IntegerField(read_only=True,help_text="是否是全日制；0->非全日制，1->全日制")employer = serializers.CharField(help_text="劳动合同主体/雇主",read_only=True, required=False,allow_blank=True)mobilePhone = serializers.CharField(help_text="电话", read_only=True, required=False, allow_blank=True)jobState = serializers.IntegerField(help_text="是否在职；0->离职，1->在职",)insuranceCode = serializers.CharField(help_text="社保流水号",read_only=True, required=False, allow_blank=True)insuranceFrom = serializers.CharField(help_text="社保开始日期",read_only=True, required=False, allow_blank=True)insuranceTo = serializers.CharField(help_text="社保结束日期",read_only=True, required=False, allow_blank=True)# sts = serializers.IntegerField(blank=True, null=True)comment = serializers.CharField(help_text="备注", read_only=True, required=False, allow_blank=True)# createDate = serializers.DateTimeField(read_only=True,required=False)# modifyDate = serializers.DateTimeField(read_only=True,required=False )graduationYears = serializers.IntegerField(help_text="毕业年限", read_only=True)entryYears = serializers.IntegerField(help_text="工作年限", read_only=True)contractValidDate = serializers.DateTimeField(help_text="劳动合同有效期",read_only=True)certFile = serializers.ListSerializer(help_text="资质证书",child=t_staff_certSerializer(),read_only=True)certNum = serializers.IntegerField(help_text="资质证书数量", )diplomaFile = serializers.ListSerializer(help_text="学历",child=t_staff_certSerializer(),read_only=True, )degreeFile = serializers.ListSerializer(help_text="学位",child=t_staff_certSerializer(),read_only=True, )
class PaginationSerializer(serializers.Serializer):current = serializers.IntegerField(help_text="当前页")pageSize = serializers.IntegerField(help_text="当前页显示数量")
class ListRequestSerializer(serializers.Serializer):current = serializers.IntegerField(help_text="当前页")pageSize = serializers.IntegerField(help_text="当前页显示数量")diploma = serializers.ListField(help_text="学历",child=serializers.CharField(required=False, allow_blank=True), min_length=1,max_length=15)degree = serializers.ListField(help_text="学位",child=serializers.CharField(required=False, allow_blank=True))certFulltime = serializers.DecimalField(help_text="全日制",max_digits=6, decimal_places=3, default=Decimal('0.0'),validators=[MinValueValidator(Decimal('0.0'))])# linenos = serializers.BooleanField(required=False)# language = LanguageSerializer(help_text="Sample help text for language")# styles = serializers.MultipleChoiceField(choices=STYLE_CHOICES, default=['solarized-dark'])xueXin = serializers.IntegerField(help_text="学信网查询", )cert = serializers.DateTimeField(help_text="资质证书，待定",required=False)employer = serializers.ListField(help_text="劳动合同主体",child=serializers.CharField(required=False, allow_blank=True))fuzzy = serializers.CharField(help_text="姓名/工号",read_only=True, required=False, allow_blank=True)graduationYearsStart = serializers.IntegerField(help_text="毕业年限开始", )graduationYearsEnd = serializers.IntegerField(help_text="毕业年限结束", )enrollYearsStart = serializers.IntegerField(help_text="入职年限开始", )enrollYearsEnd = serializers.IntegerField(help_text="入职年限结束")class ListResponsesSerializer(serializers.Serializer):"""SnippetSerializer classdoccreate: docstring for create from serializer classdoc"""list = serializers.ListSerializer(help_text="数据List",child=t_staff_infoSerializer(),read_only=True)pagination = serializers.ListSerializer(help_text="分页信息",child=PaginationSerializer(),read_only=True)class ImageSerializer(serializers.Serializer):id = serializers.IntegerField(help_text="文件id", )# fileType = serializers.CharField(help_text="文件类型",)docType = serializers.CharField(help_text="文件类型")fileName = serializers.CharField(help_text="文件名")webUrl = serializers.CharField(help_text="文件类型")createDate = serializers.DateTimeField(help_text="创建日期")modifyDate = serializers.DateTimeField(help_text="修改日期")class certsSerializer(serializers.Serializer):id = serializers.IntegerField(help_text="证书id，新增则没有该字段")
#    staffId = serializers.IntegerField(help_text="员工id，新增则没有该字段")# certType = serializers.IntegerField(help_text="证书类别：6大类")certId = serializers.IntegerField(help_text="证书ID 对应数据字典的int值")certName = serializers.CharField(help_text="证书名称")# certGrade = serializers.IntegerField(help_text="证书等级")# certMajor = serializers.IntegerField(help_text="员工id，新增则没有该字段")# certFulltime = serializers.IntegerField(help_text="员工id，新增则没有该字段")certCode = serializers.CharField(help_text="证书编号")certState = serializers.IntegerField(help_text="证书状态")certPerson = serializers.CharField(help_text="证书获得者")certOrg = serializers.CharField(help_text="颁证机构")certIssuer = serializers.CharField(help_text="签发人")certDate = serializers.DateField(help_text="颁证日期")validDate = serializers.DateField(help_text="有效日期")createDate = serializers.DateTimeField(help_text="创建日期")modifyDate = serializers.DateTimeField(help_text="修改日期")# imageId = serializers.IntegerField(help_text="文件id", )# # fileType = serializers.CharField(help_text="文件类型",)# docType = serializers.CharField(help_text="文件类型")# fileName = serializers.CharField(help_text="文件名")# webUrl = serializers.CharField(help_text="文件类型")# imageCreateDate = serializers.DateTimeField(help_text="文件创建日期")# imageModifyDate = serializers.DateTimeField(help_text="文件修改日期")file = ImageSerializer()# file = serializers.ListSerializer(help_text="文件实体对象",#                                   child=ImageSerializer())class diplomasSerializer(serializers.Serializer):id = serializers.IntegerField(help_text="证书id，新增则没有该字段")
#    staffId = serializers.IntegerField(help_text="员工id，新增则没有该字段")# certType = serializers.IntegerField(help_text="证书类别：6大类")certId = serializers.IntegerField(help_text="证书ID 对应数据字典的int值")certName = serializers.CharField(help_text="证书名称(学位证)")certGrade = serializers.IntegerField(help_text="证书等级,高中/大专/本科等")certMajor = serializers.IntegerField(help_text="专业,（是否走数据集字典，待定）")certFulltime = serializers.IntegerField(help_text="是否全日制；0->非全日制，1->全日制")certCode = serializers.CharField(help_text="证书编号")certState = serializers.IntegerField(help_text="证书状态")certPerson = serializers.CharField(help_text="证书获得者")certOrg = serializers.CharField(help_text="颁证机构")certIssuer = serializers.CharField(help_text="签发人")certDate = serializers.DateField(help_text="颁证日期")validDate = serializers.DateField(help_text="有效日期")createDate = serializers.DateTimeField(help_text="创建日期")modifyDate = serializers.DateTimeField(help_text="修改日期")# imageId = serializers.IntegerField(help_text="文件id", )# # fileType = serializers.CharField(help_text="文件类型",)# docType = serializers.CharField(help_text="文件类型")# fileName = serializers.CharField(help_text="文件名")# webUrl = serializers.CharField(help_text="文件类型")# imageCreateDate = serializers.DateTimeField(help_text="文件创建日期")# imageModifyDate = serializers.DateTimeField(help_text="文件修改日期")file = ImageSerializer()class profilesSerializer(serializers.Serializer):file = ImageSerializer()class idcardsSerializer(serializers.Serializer):file = ImageSerializer()class laborContractsSerializer(serializers.Serializer):file = ImageSerializer()class degreesSerializer(serializers.Serializer):id = serializers.IntegerField(help_text="证书id，新增则没有该字段")staffId = serializers.IntegerField(help_text="员工id，新增则没有该字段")# certType = serializers.IntegerField(help_text="证书类别：6大类")certId = serializers.IntegerField(help_text="证书ID 对应数据字典的int值")certName = serializers.CharField(help_text="学历证")certGrade = serializers.IntegerField(help_text="证书等级")certCode = serializers.CharField(help_text="证书编号")certState = serializers.IntegerField(help_text="证书状态")certPerson = serializers.CharField(help_text="证书获得者")certOrg = serializers.CharField(help_text="颁证机构")certIssuer = serializers.CharField(help_text="签发人")certDate = serializers.DateField(help_text="颁证日期")validDate = serializers.DateField(help_text="有效日期")createDate = serializers.DateTimeField(help_text="创建日期")modifyDate = serializers.DateTimeField(help_text="修改日期")file = ImageSerializer()
class AddRequestSerializer(serializers.Serializer):# created = UnixTimestampField(read_only=True)staffCode = serializers.CharField(help_text="员工编号",required=False,allow_blank=True)staffName = serializers.CharField(help_text="员工姓名",required=False, allow_blank=True)nation = serializers.CharField(help_text="国籍",required=False, allow_blank=True)bizGroup = serializers.CharField(help_text="事业群",required=False, allow_blank=True)bizDept = serializers.CharField(help_text="事业部",required=False, allow_blank=True)dept = serializers.CharField(help_text="部门",required=False, allow_blank=True)enrollDate = serializers.DateField(help_text="入职日期",required=False)graduateDate = serializers.DateField(help_text="毕业日期")workingDate = serializers.DateField(help_text="参加工作日期")birthday = serializers.DateField(help_text="出身年月日")idCardCode = serializers.CharField(help_text="身份证号", )gender = serializers.IntegerField(help_text="性别")email = serializers.CharField(help_text="邮箱", allow_blank=True)college = serializers.CharField(help_text="毕业院校", allow_blank=True)major = serializers.CharField(help_text="专业", allow_blank=True)diploma = serializers.CharField(help_text="最高学历", allow_blank=True)diplomaCode = serializers.CharField(help_text="学历证号码", allow_blank=True)degree = serializers.CharField(help_text="最高学位", allow_blank=True)degreeCode = serializers.CharField(help_text="学位证编号", allow_blank=True)majorType = serializers.CharField(help_text="专业类别",  allow_blank=True)contractUntil = serializers.DateField(help_text="合同到期日期")idCardUntil = serializers.DateField(help_text="身份证到期日期")certFulltime = serializers.IntegerField(help_text="是否是全日制；0->非全日制，1->全日制")employer = serializers.IntegerField(help_text="劳动合同主体/雇主",)mobilePhone = serializers.CharField(help_text="电话",  allow_blank=True)jobState = serializers.IntegerField(help_text="是否在职；0->离职，1->在职")insuranceCode = serializers.CharField(help_text="社保流水号",)insuranceFrom = serializers.DateField(help_text="社保开始日期",)insuranceTo = serializers.DateField(help_text="社保结束日期",)# sts = serializers.IntegerField(blank=True, null=True)comment = serializers.CharField(help_text="备注",  allow_blank=True)# createDate = serializers.DateTimeField(read_only=True,required=False)# modifyDate = serializers.DateTimeField(read_only=True,required=False )# graduationYears = serializers.IntegerField(help_text="毕业年限")# entryYears = serializers.IntegerField(help_text="工作年限")contractValidDate = serializers.DateField(help_text="劳动合同有效期",)# certNum = serializers.IntegerField(help_text="资质证书数量,本接口是否需要？待定", )certs = serializers.ListSerializer(help_text="资质证书",child=certsSerializer(),)diplomas = serializers.ListSerializer(help_text="学历",child=diplomasSerializer(),)degrees = serializers.ListSerializer(help_text="学位",child=degreesSerializer(),)# profiles = serializers.ListSerializer(help_text="简历",#                                       child=profilesSerializer())profiles = profilesSerializer()profilesSerializer()laborContracts = serializers.ListSerializer(help_text="劳动合同",child=laborContractsSerializer())idcards = idcardsSerializer()xuexins = idcardsSerializer()class DetailRequestSerializer(serializers.Serializer):result = AddRequestSerializer(help_text="员工详情页数据")

最后生成的结果如图：

基于Django框架实现前后端分离（三）相关推荐

myBatis-plus实现先按条件查询，再把查询结果分页（基于xboot框架的前后端分离项目的一部分）
一.数据库业务需求:查询数据库表test_point(里面有十个温度测试点,不同测试点有不同时间的测试温度),要把十个点的各自最新时间的数据拿到,再分页展示到页面上. sql文件: /* SQLyo ...
基于前端Vue后端.NetCore Web后台管理系统通用开本框架采用前后端分离技术，前端使用vue2.6.0，后端使用.netcore3.1，支持跨平台、多租户
基于前端Vue后端.NetCore Web后台管理系统通用开本框架采用前后端分离技术,前端使用vue2.6.0,后端使用.netcore3.1,支持跨平台.多租户.支持MySQL/SQLServer/ ...
学科投票系统-基于Python-Django实现的前后端分离项目
学科投票系统-基于Python-Django实现的前后端分离开发作者:代昌松项目详情代码请参考: vote_api:https://gitee.com/dcstempt_ping/vote_api ...
基于vue springboot的前后端分离的化妆品商城
基于vue springboot的前后端分离的化妆品商城技术介绍后端: springboot mybatis ORM框架 mysql数据库 redis分布式缓存 Druid数据库连接池前端: V ...
基于SSM+SpringBoot+Vue前后端分离的高校大学生毕业设计管理系统
大家好,很高兴和大家分享源码.不管是什么样的需求.都希望各位计算机专业的同学们有一个提高. 大家可以通过常用的搜索引擎,以百度为例,搜索源码乐园 code51 ,然后再次搜索自己想要的即可.更多的 ...
Django+Vue，前后端分离，实现用户权限认证
网上教程一大堆,要么思路不够清晰,要么给你扔一大段代码,只有几行注释.... 看了我这个,你奶奶来都能实现前后端分离用户权限认证! Django 采用token认证方式,使用 rest_framewo ...
vue和Java做数据交互_基于vue和springmvc前后端分离，json类接口调用介绍
基于vue和springmvc前后端分离,json类接口调用介绍版本要求:spring-3.2.9.RELEASE.vue-2.9.2.axios-0.17.1,其中axios作为http clie ...
首个直播商城，拼团商城,小程序商城的微服务分布式框架，前后端分离
简介: sdb mall 项目说明 sdb是一个轻量级的在renren-fast基础上利用jfinal架构二次开发的一个极速二次开发直播,拼团商城框架,前后端分离的Java快速开发平台,C端采用微信小 ...
js 获得明天0点时间戳_Python 3+Django 3 结合Vue.js框架构建前后端分离Web开发平台实战...
点击上方"测试开发技术",选择设为"设为星标" 优质文章,第一时间送达! 学习全文大概需要 12分钟,内容实战性较强. 1. 前言本篇将基于Python 3. ...

基于Django框架实现前后端分离（三）

使用drf_yasg自动生成Swagger接口文档

相关库需求的最低版本安装