介绍
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以后版本如何传参，暂时没弄明白。老版本直接在字符串中写就可以。新版本未在文档中找到解决办法，希望知道的大佬可以传授下。