Swagger 使用方法

注：本篇文章基于Django-rest-swagger 2.0.7环境下撰写

参考英文文档：

http://django-rest-swagger.readthedocs.io/en/latest/

本文是使用swagger工具结合Django-rest-framework进行restful API的管理以及可视化显示，结合今天开发的经验进行记录

1.下载：

pip install django-rest-swagger

 

2.快速搭建：

1）在Django的settings.py中：

INSTALLED_APPS = [
　　　　...
　　　　'rest_framework_swagger',
　　　  ...
]

2）在urls.py中：

from rest_framework_swagger.views import get_swagger_view
schema_view = get_swagger_view(title='Pastebin API')  #其中title='Pastebin API'为改rest api显示集合的名字(可自定义)
urlpatterns = [
　……
　url(r'^$', schema_view)
　……
]

 

3）现在开始在settings.py中设置swagger显示的内容以及显示的格式：

在settings.py中新建一个配置字典，取名SWAGGER_SETTINGS:

SWAGGER_SETTINGS = {
　　'SECURITY_DEFINITIONS':{
　　　　'basic':{
　　　　　　'type':'basic'
　　　　}
　　}
}

下面对可以添加到该配置项中的内容进行解释：

• USE_SESSION_AUTH: 可以用于切换Django Auth 的认证机制。设置为True将会显示一个 login/logout 的按钮在Swagger UI上面并且上传csrf_tokens到api中。

　　　　缺省值：True

　　　　注：这个login/logout按钮是依赖着settings里面的 LOGIN_URL 和 LOGOUT_URL，他们能够在SWAGGER_SETTINGS 或者 Django settings中进行配置。

　　　　urls.py:　　　

　　　　urlpatterns = [
　　　　　　url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
　　　　]

　　　　settings.py:　　　

　　　　LOGIN_URL = 'rest_framework:login'
　　　　LOGOUT_URL = 'rest_framework:logout'

• LOGIN_URL: 这个URL是用来在会话身份验证中进行登陆的，接收URL的命名模式。

　　　　缺省值：django.conf.settings.LOGIN_URL

• LOGOUT_URL: 这个URL是用来从身份验证会话中退出来的，接收URL的命名模式。

　　　　缺省值：django.conf.setttings.LOGOUT_URL

• SECURITY_DEFINITIONS: 这是一个安全定义的配置，配置鉴权的方法对于使用Swagger的用户，这个能够支持的类型是 basic， apiKey， oauth2。

　　　　缺省值：

　　{ 'basic':
　　　　{
　　　　　　'type': 'basic'
　　　　}
　　　}

 

接下来就是一些最基本的配置了，对于SwaggerUI：

• APIS_SORTER: 设置显示的API的排序方式。可以选择 alpha(字母顺序排)

　　　　默认值：None

• DOC_EXPANSION: API列表最开始的显示方式

　　　　可选参数：

　　　　　　None：所有api操作都折叠起来

　　　　　　'list': 列出所有的操作(仅仅是操作列表，无具体信息)

　　　　　　'full': 解释所有的操作(列出操作列表所有的具体信息，全部摊开来)

　　　　默认值：None

• JSON_EDITOR: 能够有一个图像界面去编辑复杂的api内容

　　　　默认值：False

• OPERATIONS_SORTER: 对每一个API的操作列表排序

　　　　可选参数：

　　　　　　alpah：按字母排序

　　　　　　method：按HTTP方法排序

　　　　默认值：None

• SHOW_REQUEST_HEADERS：设置True可以显示request headers

　　　　默认值：False

• SUPPORTEN_SUBMIT_METHODS：设置可以操作的HTTP方法当使用"try it out！"按钮的时候

　　　　默认值：['get', 'post', 'put', 'delete', 'patch']

• VALIDATOR_URL: 一个对于Swagger.io的在线模式验证的URL设置，能够去修改指定到本地下载或者设置 None 进行禁止

　　　　默认值：https://online.swagger.io/validator/

 

3.遇到的问题：

1）在设置好遇到了一个问题，就是会在下方提示有一个错误，错误为：schemaValidationMessages":[{"level":"error","message":"Can't read from file http://127.0.0.1:8000/swagger/swagger"}]` 

解决办法：

vi /usr/local/lib/python2.7/dist-packages/rest_framework_swagger/static/rest_framework_swagger/init.js

将其修改为如下所示：

var settings = {
　　url: window.location.pathname + '?format=openapi',
　　validatorUrl: undefined, # 添加此行
   ……