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