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 import APIView from rest_framework.permissions import AllowAny from rest_framework.schemas import SchemaGenerator from rest_framework.schemas.generators import LinkNode, insert_into from rest_framework.renderers import * from rest_framework_swagger import renderers from rest_framework.response import Response import json def response_as_json(data): json_str = json.dumps(data) response = HttpResponse(json_str, content_type='application/json') response["Access-Control-Allow-Origin"] = '*' return response def json_response(data,code=200,**kwargs): data = { "code":code, "data":data } return response_as_json(data) def json_error(error_str,code,**kwargs): data = { 'code':code, 'error':error_str, } return response_as_json(data) JsonResponse = json_response JsonError = json_error class MySchemaGenerator(SchemaGenerator): def get_links(self, request=None): links = LinkNode() paths = [] view_endpoints = [] for path, method, callback in self.endpoints: view = self.create_view(callback, method, request) path = self.coerce_path(path, method, view) paths.append(path) view_endpoints.append((path, method, view)) if not paths: return None prefix = self.determine_path_prefix(paths) for path, method, view in view_endpoints: if not self.has_view_permissions(path, method, view): continue link = view.schema.get_link(path, method, base_url=self.url) # 添加下面这一行方便在views编写过程中自定义参数. link._fields += self.get_core_fields(view) subpath = path[len(prefix):] keys = self.get_keys(subpath, method, view) insert_into(links, keys, link) return links # 从类中取出我们自定义的参数, 交给swagger 以生成接口文档. def get_core_fields(self, view): return getattr(view, 'coreapi_fields', ()) class SwaggerSchemaView(APIView): _ignore_model_permissions = True exclude_from_schema = True permission_classes = [AllowAny] renderer_classes = [ CoreJSONRenderer, renderers.OpenAPIRenderer, renderers.SwaggerUIRenderer ] def get(self, request): generator = MySchemaGenerator(title='接口', description='前后端分离接口API查询') schema = generator.get_schema(request=request) return Response(schema) 详细介绍一下上述代码实现的功能，从参考的网页中看到他们调入的序列化库不外乎是将代码转为json格式，但是我们的json库完全够用，因此就写了三个函数作为转json使用，相比大家也能够看明白；其次，MySchemaGenerator继承自SchemaGenerator并重写了部分代码，以实现自定义参数。

再往views中添加一个功能用于测试

class ReturnJson(APIView): def get(self,request,*args,**kwargs): return JsonResponse('测试用例')

3-配置url.py

url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')), url(r'^docs/', views.SwaggerSchemaView.as_view(), name='apiDocs'),

4-测试

python manage.py runserver 8000

输入127.0.0.1:8000/docs查看结果如下图 到这里，我们的框架已经成功搭建了。Mission Success近在眼前。从页面里看到，我们无法进行传参，无法告知前端我们需要什么样的参数，是字符串？还是文件？有木有详细说明？或者举个例子？

这就需要我们在views.py文件中继续定义一个传递参数的函数，如下：

# 定义参数传递 import coreapi from django.http import QueryDict from rest_framework.request import Request def DocParam(name= 'default',location='', required = False,description =None,type = 'string', *args,**kwargs): return coreapi.Field(name=name,location=location,required=required,description=description,type=type) # 编写参数统一处理的方法 def get_parameter_dic(request,*args,**kwargs): if isinstance(request,Request) == False: return {} query_params = request.query_params if isinstance(query_params,QueryDict): query_params = query_params.dict() result_data = request.data if isinstance(result_data,QueryDict): result_data = result_data.dict() if query_params != {}: return query_params else: return result_data

为什么要编写参数统一处理的方法？简单地说你去试一下便知，如果不编写，出的错误你也会看的很明白。若想深入理解编写参数同意的方法，可以参考文章开头博主提到那位大神，他在文章中说的很明确。

我们为项目的ReturnJson添加一个传参，再为项目添加一个POST功能函数，实现文件上传，并返回具体的Error信息来测试上文的所有功能。别忘了在url中添加post的url

class ReturnJson(APIView): coreapi_fields = ( DocParam("token"), DocParam("contract_type") ) def get(self,request,*args,**kwargs): params = get_parameter_dic(request) return JsonResponse(data=params,code=102) class Approval(APIView): coreapi_fields = ( DocParam('contract_file',location='formData',type='file',description='上传文件'), DocParam('contract_type',location ='query',description='合同工类型') ) def post(self,request,*args,**kwargs): if request.method == 'POST': file = request.FILES.get('contract_file') params = get_parameter_dic(request) if not file and 'contract_type' not in params: error = 'Please Select a File and Select contract_type' return JsonError(error, 101) elif not file: error = 'Please Select a File' return JsonError(error, 102) elif 'contract_type' not in params: error = 'Please Select Contract Type' return JsonError(error, 103) else: contract_type = params['contract_type'] return JsonResponse("success")

访问docs返回结果如下图：

前段就可以在Swagger页面中测试参数，填写参数并调试后端返回的信息了。

这样，我们就可以在我们的项目中使用Django-Swagger这个前后端分离API文档自动生成的框架了，这能给后端开发者省去很多的时间。当然还是那句话，对于已经搭建好的项目，改代码太麻烦啦，写API文档吧，对于不喜欢DS的大神，写API文档吧！