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