Django-Rest-Swagger搭建前后端分离API文档
前沿:最近工作需要,做项目需要前后端分离,那么前段与后端的“沟通”就成了项目执行效率的一大障碍。我们尝试过去写API说明文档,但试想一下,作为一个后端工程师,你不光需要修改后端代码,还要去撰写API文档,使得你的工作量剧增,WTF?作为一个能省事儿绝不多敲一行字的鞋狗程序员,希望吧更多的时间投入球鞋“冲冲冲”中,就尝试搭建一个Django-Swagger框架,非常便捷的实现前后端API交互。话不多说,开始正文↓
什么是Django-Swagger
Django大家并不陌生,后端开发的一个框架。而对于Swagger,想必做前端的并不陌生,但对于做后端的我,听到Swagger我的第一反应就是摇起来!Wow Fantastic Baby!我就去百度Swagger,大致了解了Swagger是什么,能做什么。简单的说,Django-Swagger其实就是在Django项目中使用Swagger框架,使得在做后端开发的同时自动生成一个API文档供前端查看。看到“自动”两个字,是不是很有动力?不过搭建DS也有一个弊端,对于已经写好的后端代码,搭建DS需要修改大量的代码,我还是劝你去敲API文档吧lol!但对于全新的一个项目,DS是一个很好的选择。
但是,看了许久貌似对我的项目没有太大的帮助呀,How Should I Do?在查资料的过程中,从某书(JS)网站上看到一位名为“行如风”的大神与2017年写的代码,对我启发很大,那么我也是在他代码的基础上进行的Django-Swagger搭建。
环境配置
Django-Swagger依赖于:
djangorestframework 3.7.1
django-rest-swagger 2.1.2
建议先安装djangorestframework,再安装django-rest-swagger。至于版本问题,不同的版本在代码上有所调整,可能不适用与我的代码,我装载的版本是严格与上述一致的。(不然真的会出很多问题,不信你可以试试~)
我默认你会创建一个django项目,并且创建了一个app。在这里我创建了一个名为Swagger的项目,并在项目内部创建了一个名为api的app。接下来我们就开始搭建swagger框架。
搭建DS框架
1-配置settings.py
在INSTALLED_APPS中添加‘api’app、‘rest_framework’、‘rest_frame_work_swagger’。并添加swagger配置项。
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'api',
'rest_framework',
'rest_framework_swagger'
]
REST_FRAMEWORK = {
# 下面这一行表示接口文档的访问权限, AllowAny不做权限限制.
'DEFAULT_PERMISSION_CLASSES': ('rest_framework.permissions.AllowAny',),
# 'PAGE_SIZE': 10,
'PAGINATE_BY':10,
}
# swagger 配置项
SWAGGER_SETTINGS = {
# 基础样式
'SECURITY_DEFINITIONS': {
"basic":{
'type': 'basic'
}
},
# 如果需要登录才能够查看接口文档, 登录的链接使用restframework自带的.
# 'LOGIN_URL': 'rest_framework:login',
# 'LOGOUT_URL': 'rest_framework:logout',
# 'DOC_EXPANSION': None,
# 'SHOW_REQUEST_HEADERS':True,
# 'USE_SESSION_AUTH': True,
# 'DOC_EXPANSION': 'list',
# 接口文档中方法列表以首字母升序排列
'APIS_SORTER': 'alpha',
# 如果支持json提交, 则接口文档中包含json输入框
'JSON_EDITOR': True,
# 方法列表字母排序
'OPERATIONS_SORTER': 'alpha',
'VALIDATOR_URL': None,
}
2-写入api/views.py
那我们在写views.py之前,就会想一般我们是先有路由,再写views,那在这里为什么需要先写views呢?从我们项目的需求来想,我们需要的功能使然,我们不需要像别的教程那样序列化(Serialize)一个Model,我们只需要对我们的功能函数进行封装,并处理成Swagger能识别的编码格式,因此我们需要对一个类进行重写,同时前后端之间的通信是以JSON格式进行的,我们也需要写一下简单的处理函数(当然不写也可以,全凭自己喜好)。
概括的说,我们先写views不是写功能,是写“配置”。
from django.http import HttpResponse
from rest_framework.views