介绍

我们在实际的开发工作中需要将django框架与swagger进行集成,用于生成API文档。网上也有一些关于django集成swagger的例子,但由于每个项目使用的依赖版本不一样,因此可能有些例子并不适合我们。我也是在实际集成过程中遇到了一些问题,例如如何自定义参数等问题,最终成功集成,并将结果分享给大家。

开发版本

我开发使用的依赖版本,我所使用的都是截止发稿日期为止最新的版本:

Django 2.2.7

django-rest-swagger 2.2.0

djangorestframework 3.10.3

修改settings.py

1、项目引入rest_framework_swagger依赖

INSTALLED_APPS = [
 ......
 'rest_framework_swagger',
 ......
]

2、设置DEFAULT_SCHEMA_CLASS,此处不设置后续会报错。

REST_FRAMEWORK = {
 ......
 'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.AutoSchema',
 ......
}

在app下面创建schema_view.py

在此文件中,我们要继承coreapi中的SchemaGenerator类,并重写get_links方法,重写的目的就是实现我们自定义参数,并且能在页面上展示。此处直接复制过去使用即可。

from rest_framework.schemas import SchemaGenerator
from rest_framework.schemas.coreapi import LinkNode, insert_into
from rest_framework.renderers import *
from rest_framework_swagger import renderers
from rest_framework.response import Response
from rest_framework.decorators import APIView
from rest_framework.permissions import AllowAny,IsAuthenticated,IsAuthenticatedOrReadOnly
from django.http import JsonResponse

class MySchemaGenerator(SchemaGenerator):

 def get_links(self, request=None):
  links = LinkNode()

  paths = []
  view_endpoints = []
  for path, method, callback in self.endpoints:
   view = self.create_view(callback, method, request)
   path = self.coerce_path(path, method, view)
   paths.append(path)
   view_endpoints.append((path, method, view))

  # Only generate the path prefix for paths that will be included
  if not paths:
   return None
  prefix = self.determine_path_prefix(paths)

  for path, method, view in view_endpoints:
   if not self.has_view_permissions(path, method, view):
    continue
   link = view.schema.get_link(path, method, base_url=self.url)
   # 添加下面这一行方便在views编写过程中自定义参数.
   link._fields += self.get_core_fields(view)

   subpath = path[len(prefix):]
   keys = self.get_keys(subpath, method, view)

   # from rest_framework.schemas.generators import LinkNode, insert_into
   insert_into(links, keys, link)

  return links

 # 从类中取出我们自定义的参数, 交给swagger 以生成接口文档.
 def get_core_fields(self, view):
  return getattr(view, 'coreapi_fields', ())

class SwaggerSchemaView(APIView):
 _ignore_model_permissions = True
 exclude_from_schema = True

 #permission_classes = [AllowAny]
 # 此处涉及最终展示页面权限问题,如果不需要认证,则使用AllowAny,这里需要权限认证,因此使用IsAuthenticated
 permission_classes = [IsAuthenticated]
 # from rest_framework.renderers import *
 renderer_classes = [
  CoreJSONRenderer,
  renderers.OpenAPIRenderer,
  renderers.SwaggerUIRenderer
 ]

 def get(self, request):
  # 此处的titile和description属性是最终页面最上端展示的标题和描述
  generator = MySchemaGenerator(title='API说明文档',description='''接口测试、说明文档''')

  schema = generator.get_schema(request=request)

  # from rest_framework.response import Response
  return Response(schema)


def DocParam(name="default", location="query",required=True, description=None, type="string",
    *args, **kwargs):
 return coreapi.Field(name=name, location=location,
       required=required, description=description,
       type=type)

实际应用

在你的应用中定义一个接口,并发布。我这里使用一个测试接口进行验证。

注意

1、所有的接口必须采用calss的方式定义,因为要继承APIView。

2、class下方的注释post,是用来描述post方法的作用,会在页面上进行展示。

3、coreapi_fields 中定义的属性name是参数名称,location是传值方式,我这里一个采用query查询,一个采用header,因为我们进行身份认证,必须将token放在header中,如果你没有,去掉就好了,这里的参数根据你实际项目需要进行定义。

4、最后定义post方法,也可以是get、put等等,根据实际情况定义。

# 这里是之前在schema_view.py中定义好的通用方法,引入进来 
from app.schema_view import DocParam

'''
 测试
'''
class CustomView(APIView):
 '''
 post:
  测试测试测试
 '''
 coreapi_fields = (
  DocParam(name="id",location='query',description='测试接口'),
  DocParam(name="AUTHORIZATION", location='header', description='token'),
 )

 def post(self, request):
  print(request.query_params.get('id'));
  return JsonResponse({'message':'成功!'})

5、接收参数这块一定要注意,我定义了一个公用的方法,这里不做过多阐述,如实际过程遇到应用接口与swagger调用接口的传值问题,可参考如下代码。

def getparam(attr,request):
 obj = request.POST.get(attr);
 if obj is None:
  obj = request.query_params.get(attr);
 return obj;

修改url.py

针对上一步中定义的测试接口,我们做如下配置。

from django.contrib import admin
from rest_framework import routers
from django.conf.urls import url,include

# 下面是刚才自定义的schema
from app.schema_view import SwaggerSchemaView
# 自定义接口
from app.recommend import CustomView

router = routers.DefaultRouter()

urlpatterns = [
 # swagger接口文档路由
 url(r"^docs/$", SwaggerSchemaView.as_view()),
 url(r'^admin/', admin.site.urls),
 url(r'^', include(router.urls)),
 # drf登录
 url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))

 # 测试接口
 url(r'^test1', CustomView.as_view(), name='test1'),
]

效果展示

访问地址:http://localhost:8001/docs/

浅谈django框架集成swagger以及自定义参数问题

浅谈django框架集成swagger以及自定义参数问题

总结

以上这篇浅谈django框架集成swagger以及自定义参数问题就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家多多支持。

广告合作:本站广告合作请联系QQ:858582 申请时备注:广告合作(否则不回)
免责声明:本站资源来自互联网收集,仅供用于学习和交流,请遵循相关法律法规,本站一切资源不代表本站立场,如有侵权、后门、不妥请联系本站删除!

《魔兽世界》大逃杀!60人新游玩模式《强袭风暴》3月21日上线

暴雪近日发布了《魔兽世界》10.2.6 更新内容,新游玩模式《强袭风暴》即将于3月21 日在亚服上线,届时玩家将前往阿拉希高地展开一场 60 人大逃杀对战。

艾泽拉斯的冒险者已经征服了艾泽拉斯的大地及遥远的彼岸。他们在对抗世界上最致命的敌人时展现出过人的手腕,并且成功阻止终结宇宙等级的威胁。当他们在为即将于《魔兽世界》资料片《地心之战》中来袭的萨拉塔斯势力做战斗准备时,他们还需要在熟悉的阿拉希高地面对一个全新的敌人──那就是彼此。在《巨龙崛起》10.2.6 更新的《强袭风暴》中,玩家将会进入一个全新的海盗主题大逃杀式限时活动,其中包含极高的风险和史诗级的奖励。

《强袭风暴》不是普通的战场,作为一个独立于主游戏之外的活动,玩家可以用大逃杀的风格来体验《魔兽世界》,不分职业、不分装备(除了你在赛局中捡到的),光是技巧和战略的强弱之分就能决定出谁才是能坚持到最后的赢家。本次活动将会开放单人和双人模式,玩家在加入海盗主题的预赛大厅区域前,可以从强袭风暴角色画面新增好友。游玩游戏将可以累计名望轨迹,《巨龙崛起》和《魔兽世界:巫妖王之怒 经典版》的玩家都可以获得奖励。