Django REST Swagger

介绍

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/，效果如下图：

1583031702542

渲染架构

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

效果如下：

1582968675099

# 将其设置为False，效果如下图
SWAGGER_SETTINGS = {
    'USE_SESSION_AUTH': False, 
}

1582968744860

注意： “登录/注销”按钮取决于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以后版本如何传参，暂时没弄明白。老版本直接在字符串中写就可以。新版本未在文档中找到解决办法，希望知道的人可以传授下。

介绍

安装

快速使用

渲染架构

get_swagger_view快捷方式

高级用法

Settings

认证方式

USE_SESSION_AUTH

LOGIN_URL

LOGOUT_URL

SECURITY_DEFINITIONS

SwaggerUI设置

APIS_SORTER

DOC_EXPANSION

JSON_EDITOR

OPERATIONS_SORTER

SHOW_REQUEST_HEADERS

SUPPORTED_SUBMIT_METHODS

VALIDATOR_URL

自定制模板

模板

版本标题

猜你喜欢

`get_swagger_view`快捷方式