使用drf_yasg自动生成Swagger接口文档
相关库需求的最低版本安装
Pillow>=4.3.0
django-filter>=2.4.0
djangorestframework-camel-case>=1.1.2
djangorestframework-recursive>=0.1.2
dj-database-url>=0.4.2
user_agents>=1.1.0
django-cors-headers
drf_yasg
django-oauth-toolkit>=1.3.0
可以将上述代码写到requirements.txt中,然后到该文件所在目录中执行
pip install -U -r requirements.txt
如果没有安装pip,先执行:
python -m pip install -U pip setuptools
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_view
swagger_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_slash
router = 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 viewsets
from 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.data
print('详情页请求数据', 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 serializers
class 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 classdoc
create: 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="员工详情页数据")
最后生成的结果如图: