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, # 添加此行
   ……

 

posted @ 2016-10-25 23:50 ShaunChen 阅读(...) 评论(...) 编辑 收藏