这是我参与更文挑战的第2天，活动详情查看： 更文挑战
Swagger是什么？它能干什么？
发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。
框架说明及使用
1.说明
现在SWAGGER官网主要提供了几种开源工具，提供相应的功能。可以通过配置甚至是修改源码以达到你想要的效果。
Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
PS：
Springfox Swagger: Spring 基于swagger规范，可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。
2.基于Spring框架的Swagger流程应用
这里不会介绍Swagger的工具具体如何使用，不会讲yml或者json格式描述文件的语法规范，也不会讲如何在SpringMVC或者Spring Boot中配置Springfox－swagger。这些都能从网上找到，而且配置起来都非常的简单。
这里想讲的是如何结合现有的工具和功能，设计一个流程，去保证一个项目从开始开发到后面持续迭代的时候，以最小代价去维护代码、接口文档以及Swagger描述文件。
2.1 项目开始阶段
一般来说，接口文档都是由服务端来编写的。在项目开发阶段的时候，服务端开发可以视情况来决定是直接编写服务端调用层代码，还是写Swagger描述文件。建议是如果项目启动阶段，就已经搭好了后台框架，那可以直接编写服务端被调用层的代码（即controller及其入参出参对象），然后通过Springfox－swagger 生成swagger json描述文件。如果项目启动阶段并没有相关后台框架，而前端对接口文档追得紧，那就建议先编写swagger描述文件，通过该描述文件生成接口文档。后续后台框架搭好了，也可以生成相关的服务端代码。
2.2 项目迭代阶段
到这个阶段，事情就简单很多了。后续后台人员，无需关注Swagger描述文件和接口文档，有需求变更导致接口变化，直接写代码就好了。把调用层的代码做个修改，然后生成新的描述文件和接口文档后，给到前端即可。真正做到了一劳永逸。
2.3流程
总结一下就是通过下面这两种流程中的一种，可以做到代码和接口文档的一致性，服务端开发再也不用花费精力去维护接口文档。
给Mock系统的正常请求及响应全流程数据 很多时候，如果你能在提供接口文档的同时，把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统，直接将这些模拟数据录入到Mock系统中，那将会提高前端的开发效率，减少许多发生在联调时候才会发生的问题。
通过适当地在代码中加入swagger的注解，可以让你的接口文档描述信息更加详细，如果你把每个出入参数的示例值都配上，那前端就可以直接在接口文档中拿到模拟数据。相关的注解类及参数配置可以参考文末他人写的技术文章，这里也不作展开了。
Python 相关配置
当前virtualenv 环境下
pip install django-rest-swagger==2.2.0
在Django项目settings.py中 加入 插件模块
DEBUG = True
ALLOWED_HOSTS = []
# Application definition
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'Api.apps.ApiConfig',
'crispy_forms',
'rest_framework',
'django_filters',
'rest_framework_swagger' # Swagger 接口文档自动集成平台
]
二 在views.py中 在接口授权里 设置说明 如下图 注释字体就是说明 在这里插入图片描述
# import os,django
# os.environ.setdefault("DJANGO_SETTINGS_MODULE", "project_name.settings")
# django.setup()
from django.shortcuts import render
# from django.contrib.auth.models import User,Group
from rest_framework import viewsets
from Api.serializers import UserSerializer,GroupSerializer
from Api.models import User,Group
from rest_framework.schemas import get_schema_view
# Create your views here.
class UserViewSet(viewsets.ModelViewSet):
"""
retrieve:
Return a user instance.
list:
Return all users,odered by most recent joined.
create:
Create a new user.
delete:
Remove a existing user
partial_update:
Update one or more fields on a existing user.
update:
Update a user.
"""
queryset = User.objects.all()
serializer_class = UserSerializer
class GroupViewSet(viewsets.ModelViewSet):
"""
retrieve:
Return a group instance.
list:
Return all groups, ordered by most recently joined.
create:
Create a new group.
delete:
Remove an existing group.
partial_update:
Update one or more fields on an existing group.
update:
Update a group.
"""
queryset = Group.objects.all()
serializer_class = GroupSerializer
三 配置urls.py 设置路由 可访问Swagger 接口文档自动集成平台
# 导入 admin Django内置admin
from django.contrib import admin
# 导入 path 设置路由
from django.urls import path
from django.urls import include, path
# rest_framework相关
from rest_framework import routers
from Api import views
# swagger相关必须导入
from rest_framework.schemas import get_schema_view
from rest_framework_swagger.renderers import SwaggerUIRenderer,OpenAPIRenderer
# rest_framework配置
router = routers.DefaultRouter()
router.register(r'users',views.UserViewSet)
router.register(r'groups',views.GroupViewSet)
swagger配置
schema_view = get_schema_view(title='Users API', renderer_classes=[OpenAPIRenderer, SwaggerUIRenderer])
urlpatterns = [
# 可通过docs/访问Swagger 接口文档自动集成平台
path(r'docs/', schema_view, name="docs"),
path('admin/', admin.site.urls),
path('',include(router.urls)),
path('api-auth/',include('rest_framework.urls',namespace='rest_framework')),
]
本次安装用的是python 3.5 Django==2.0.3 超出范围可能报错 这是整套项目包含的插件 方便以后查阅使用
Package Version
----------------------- ------------
amqp 1.4.9
anyjson 0.3.3
attrs 19.3.0
Babel 2.8.0
bcrypt 3.1.7
billiard 3.3.0.23
celery 3.1.26.post2
certifi 2019.11.28
cffi 1.13.2
chardet 3.0.4
Click 7.0
colorama 0.4.3
colorlog 4.1.0
ConfigArgParse 0.15.1
coreapi 2.3.3
coreschema 0.0.4
cryptography 2.8
defusedxml 0.6.0
diff-match-patch 20181111
Django 2.0.3
django-celery 3.3.1
django-crispy-forms 1.7.2
django-filter 2.2.0
django-formtools 2.2
django-import-export 2.0.1
django-rest-swagger 2.2.0
django-six 1.0.4
django-xadmin 0.5.0
djangorestframework 3.9.2
dwebsocket 0.5.12
et-xmlfile 1.0.1
eventlet 0.22.1
filetype 1.0.5
Flask 1.1.1
flower 0.9.3
future 0.18.2
gevent 1.5a2
geventhttpclient-wheels 1.3.1.dev2
greenlet 0.4.15
har2case 0.3.1
httprunner 2.5.4
idna 2.6
importlib-metadata 1.5.0
itsdangerous 1.1.0
itypes 1.1.0
jdcal 1.4.1
Jinja2 2.11.1
jsonpath 0.82
jsonschema 3.2.0
kombu 3.0.37
locust 0.0
locustio 0.13.5
Markdown 3.1.1
MarkupPy 1.14
MarkupSafe 1.1.1
msgpack-python 0.5.6
odfpy 1.4.1
openapi-codec 1.3.2
openpyxl 2.6.4
paramiko 2.7.1
Pillow 6.2.2
pip 20.0.2
pycparser 2.19
PyMySQL 0.9.3
PyNaCl 1.3.0
pyrsistent 0.15.7
pytz 2019.3
PyYAML 5.3
pyzmq 18.1.1
requests 2.22.0
requests-toolbelt 0.9.1
sentry-sdk 0.13.5
setuptools 45.1.0
simplejson 3.17.0
six 1.14.0
sqlparse 0.3.0
tablib 0.14.0
tornado 5.1.1
uritemplate 3.0.1
urllib3 1.22
Werkzeug 0.16.1
wheel 0.34.2
xlrd 1.2.0
xlwt 1.3.0
zipp 1.1.0
运行Swagger 接口文档自动集成平台
