Django-Rest-Swagger搭建前后端分离API文档

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