介紹
已經停止更新，推薦使用drf-yasg
Django REST框架的Swagger / OpenAPI文檔生成器。幫助我們生成api文檔。
安裝
pip install django-rest-swagger
將rest-framework-swagger注冊到app中，如下：
settings.py
INSTALLED_APPS = [
...
'rest_framework_swagger',
...
]
注意：如果使用的是新版本的django-rest-framework，需要在配置中添加如下內容，否則會報錯：
# 錯誤信息
AttributeError: 'AutoSchema' object has no attribute 'get_link'
# REST framework
REST_FRAMEWORK = {
...
# 新版drf schema_class默認用的是rest_framework.schemas.openapi.AutoSchema
'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
...
}
快速使用
要快速入門，請使用get_swagger_view快捷方式。這將產生一個使用通用設置的架構視圖。有關更高級的用法，請參閱“schemas”部分。
示例
urls.py
from django.conf.urls import url
from rest_framework_swagger.views import get_swagger_view
schema_view = get_swagger_view(title='API') # title就是文檔的名字
urlpatterns = [
url(r'^docs/$', schema_view)
]
views.py
class Users(APIView):
"""
get: user信息
post: 修改user信息
"""
def get(self, request):
return Response({'name': 'liu'})
def post(self, request):
return Response({'age': 18})
訪問 http://127.0.0.1:8000/docs/，效果如下圖：
渲染架構
Django REST Swagger包含兩個渲染器。OpenAPIRenderer和 SwaggerUIRenderer。
OpenAPIRenderer是負責生成JSON規范，而SwaggerUIRenderer呈現UI（HTML / JS / CSS）。
注意：要呈現UI，必須包括兩個渲染器。如果希望自定義用戶界面，OpenAPIRenderer可以單獨使用。
get_swagger_view快捷方式
為方便起見，提供了具有合理默認配置的快捷方式來為您的API生成SwaggerUI文檔。該視圖具有以下特點：
- 強制執行DRF權限類和用戶上下文。這意味着，如果視圖需要身份驗證，匿名用戶可能看不到完整的端點列表。
- 任何人都可以查看文檔，但是，只會為公開可用的端點生成文檔。
- 渲染CoreJSON
參數：
title：文檔的標題（缺省：None）
url：文檔的URL（如果不在同一主機或路徑上）。可以是相對路徑，也可以是絕對URL。（默認值：None）
高級用法
為了更好地控制文檔，請使用基於函數的視圖或基於類的視圖來創建自己的架構視圖。如果要生成特定URL模式或URL conf的文檔，這將很有用。
有關模式生成器的更多詳細文檔，請參見：
http://www.django-rest-framework.org/api-guide/schemas/
示例：基於類的視圖
from rest_framework.permissions import AllowAny
from rest_framework.response import Response
from rest_framework.schemas import SchemaGenerator
from rest_framework.views import APIView
from rest_framework_swagger import renderers
class SwaggerSchemaView(APIView):
permission_classes = [AllowAny]
renderer_classes = [
renderers.OpenAPIRenderer,
renderers.SwaggerUIRenderer
]
def get(self, request):
generator = SchemaGenerator()
# request參數也不是必須的，如果要將每個用戶的權限應用於生成的架構，則可以使用該參數。
schema = generator.get_schema(request=request)
return Response(schema)
# urls.py
urlpatterns = [
path('admin/', admin.site.urls),
path('user/', Users.as_view()),
path('swagger/', SwaggerSchemaView.as_view()), # 訪問該地址同樣會展示接口文檔
]
示例：基於函數的視圖
from rest_framework_swagger.renderers import OpenAPIRenderer, SwaggerUIRenderer
from rest_framework.decorators import api_view, renderer_classes
from rest_framework import response, schemas
@api_view()
@renderer_classes([SwaggerUIRenderer, OpenAPIRenderer])
def schema_view(request):
generator = schemas.SchemaGenerator(title='Pastebin API')
return response.Response(generator.get_schema(request=request))
Settings
Django REST Swagger的配置與Django REST框架相同。可以在Settings.py中通過定義 SWAGGER_SETTINGS 來配置設置。
示例
settings.py
# swagger 配置項
SWAGGER_SETTINGS = {
# 基礎樣式
'SECURITY_DEFINITIONS': {
"basic":{
'type': 'basic'
}
},
# 如果需要登錄才能夠查看接口文檔, 登錄的鏈接使用restframework自帶的.
'LOGIN_URL': 'rest_framework:login',
'LOGOUT_URL': 'rest_framework:logout',
# 'DOC_EXPANSION': None,
# 'SHOW_REQUEST_HEADERS':True,
# 'USE_SESSION_AUTH': True,
# 'DOC_EXPANSION': 'list',
# 接口文檔中方法列表以首字母升序排列
'APIS_SORTER': 'alpha',
# 如果支持json提交, 則接口文檔中包含json輸入框
'JSON_EDITOR': True,
# 方法列表字母排序
'OPERATIONS_SORTER': 'alpha',
'VALIDATOR_URL': None,
}
認證方式
USE_SESSION_AUTH
切換使用Django Auth作為身份驗證機制。將其設置為True將會在Swagger UI上顯示一個登錄/注銷按鈕，並將csrf_tokens發布到API。
默認： True
效果如下：
# 將其設置為False，效果如下圖
SWAGGER_SETTINGS = {
'USE_SESSION_AUTH': False,
}
注意： “登錄/注銷”按鈕取決於LOGIN_URL和LOGOUT_URL設置，默認為/accounts/login。這些可以在SWAGGER_SETTINGS或Django設置下進行配置。
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'
# 方式二
SWAGGER_SETTINGS = {
'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.settings.LOGOUT_URL
SECURITY_DEFINITIONS
安全定義配置Swagger可以使用哪些身份驗證方法。目前由OpenAPI的2.0規范支持的方案類型basic，apiKey和oauth2。
有關可用選項的更多信息，請查閱OpenAPI 安全對象定義。
默認：
{
'basic': {
'type': 'basic'
}
}
SwaggerUI設置
以下是SwaggerUI的一些基本配置設置。請注意，對於更高級的用例，您可能希望編寫自己的rest_framework_swagger/static/init.js文件。
APIS_SORTER
設置為alpha啟用字母排序。
默認： None
DOC_EXPANSION
控制API列表的顯示方式。可以設置為：
None：所有操作均已折疊"list"：列出所有操作"full"：擴展所有操作
默認： None
SWAGGER_SETTINGS = {
...
'DOC_EXPANSION': 'list',
}
JSON_EDITOR
啟用用於編輯復雜實體的圖形視圖。
默認： False
OPERATIONS_SORTER
對每個API的操作列表進行排序。可以設置為：
alpha：按字母順序排序method：按HTTP方法排序
默認： None
SHOW_REQUEST_HEADERS
設置為True顯示請求標頭。
默認： False
SUPPORTED_SUBMIT_METHODS
可以使用“ Try it out! ”與HTTP方法列表進行交互。按鈕。
默認： ['get', 'post', 'put', 'delete', 'patch']
VALIDATOR_URL
swagger.io的在線模式驗證器的URL。可以修改為指向本地安裝，或設置None為禁用。
默認： https://online.swagger.io/validator/
自定制模板
模板
可以通過覆蓋來自定義SwaggerUIRenderer所使用的模板 rest_framework_swagger/index.html。
以下是一些可以自定義的基本區域：
{% block extra_styles %}添加其他樣式表{% block extra_scripts %}添加其他腳本。{% block user_context_message %}自定義“您好，用戶”消息（僅限Django會話）{% block extra_nav %}導航欄中其他內容的占位符。{% block logo %}導航欄的徽標區域。
版本標題
以下代碼會將版本號附加到每個請求中，這是必需的rest_framework.versioning.AcceptHeaderVersioning。這應該進入rest_framework_swagger/index.html您的模板路徑。
{% extends "rest_framework_swagger/base.html" %}
{% block extra_scripts %}
<script type="text/javascript">
$(function () {
var ApiVersionAuthorization = function () {};
ApiVersionAuthorization.prototype.apply = function (obj) {
obj.headers['Accept'] += '; version=1.0';
return true;
};
swaggerUi.api.clientAuthorizations.add(
'api_version',
new ApiVersionAuthorization()
);
});
</script>
{% endblock extra_scripts %}
注：2.0以后版本如何傳參，暫時沒弄明白。老版本直接在字符串中寫就可以。新版本未在文檔中找到解決辦法，希望知道的大佬可以傳授下。