转载

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

介绍

我们在实际的开发工作中需要将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以及自定义参数问题就是小编分享给大家的全部内容了，希望能给大家一个参考，也希望大家多多支持我们。

时间：2020-07-06

Django REST Swagger实现指定api参数

为什么要指定swagger的api参数 api的参数有多种类型: query 参数,如 /users?role=admin path 参数,如 /users/{id} header 参数,如 X-MyHeader: Value body 参数,描述POST,PUT,PATCH请求的body form 参数,描述 Content-Type of application/x-www-form-urlencoded 和 multipart/form-data 的请求报文body的参数 swagger指

浅谈python抛出异常、自定义异常, 传递异常

一. 抛出异常 Python用异常对象(exception object)表示异常情况,遇到错误后,会引发异常.如果异常对象并未被处理或捕捉,程序就会用所谓的回溯(Traceback,一种错误信息)终止执行. raise 语句 Python中的raise 关键字用于引发一个异常,基本上和C#和Java中的throw关键字相同,如下所示: import traceback def throw_error(): raise Exception("抛出一个异常")#异常被抛出,print函数

django-rest-framework 自定义swagger过程详解

前言之前的文章编写了一个返回json的例子,直接用浏览器进行get请求虽然成功了, 但是接口文档的样式很难看, 不好用. 而且提示没有访问权限. 我们一般都希望能够直接在接口文档中进行请求, 以测试接口, 本篇文章中会给出一个自定义swagger(openapi)的例子. 使接口文档变得美观可用, 可以填写参数, 可以进行请求以观察数据格式, 测试接口是否可用. 环境 workon python35 pip list chardet (3.0.4) coreapi (2.3.3) coresc

浅谈django的render函数的参数问题

hello.html 文件代码如下: HelloWorld/templates/hello.html 文件代码: <h1>{{ hello }}</h1> HelloWorld/HelloWorld/view.py 文件代码: # -*- coding: utf-8 -*- #from django.http import HttpResponse from django.shortcuts import render def hello(request): context = {

浅谈Vue中render中的h箭头函数

vue2.0新增了render方法,官方案例写的是: render: h=>h(app) 其中h是由createElement方法演变而来 render: function(createElement){ return createElement(app) } 用es6的写法就是:(只有一个个return语句,可以省略return和{}) render: createElement=>createElement(app) 将createElement改成 h 就是官方写法. 使用 h 的理由,

浅谈django中的认证与登录

认证登录 django.contrib.auth中提供了许多方法,这里主要介绍其中的三个: 1 authenticate(**credentials) 提供了用户认证,即验证用户名以及密码是否正确一般需要username password两个关键字参数如果认证信息有效,会返回一个 User 对象.authenticate()会在User 对象上设置一个属性标识那种认证后端认证了该用户,且该信息在后面的登录过程中是需要的.当我们试图登陆一个从数据库中直接取出来不经过authent

浅谈django开发者模式中的autoreload是如何实现的

在开发django应用的过程中,使用开发者模式启动服务是特别方便的一件事,只需要 python manage.py runserver 就可以运行服务,并且提供了非常人性化的autoreload机制,不需要手动重启程序就可以修改代码并看到反馈.刚接触的时候觉得这个功能比较人性化,也没觉得是什么特别高大上的技术.后来有空就想着如果是我来实现这个autoreload会怎么做,想了很久没想明白,总有些地方理不清楚,看来第一反应真是眼高手低了.于是就专门花了一些时间研究了django是怎样实现autor

浅谈Django自定义模板标签template_tags的用处

自定义模板标签,过滤器.英文翻译是Customtemplatetagsandfilters.customfilter自定义过滤器今天不在我的记录范围之内,以后用到再看官方文档也不迟. **问题1:**customtemplatetags到底长啥样? customtemplatetags-github Manytemplatetagstakeanumberofarguments–stringsortemplatevariables–andreturnaresultafterdoingsomepro

浅谈Django中的数据库模型类-models.py(一对一的关系)

如下所示: # -*- coding: utf-8 -*- from __future__ import unicode_literals from django.db import models # Create your models here. # 一对一关系:数据库中两个表中数据的对应关系 # 一个账户对应着一个联系人,而一个联系人有一个账户 # 一对一关系是通过在两个表之间定义相同的主键来完成 class Account(models.Model): username = models

浅谈Django QuerySet对象(模型.objects)的常用方法

准备工作: 新建一个项目,在项目中新家一个app,名字自取.将app添加值settings.py中,然后配置settings连接数据库. 在app中的models中新建模型: from django.db import models # Create your models here. class Author(models.Model): """作者模型""" name = models.CharField(max_length=100) ag

浅谈Javascript中的函数、this以及原型

关于函数在Javascript中函数实际上就是一个对象,具有引用类型的特征,所以你可以将函数直接传递给变量,这个变量将表示指向函数"对象"的指针,例如: function test(message){ alert(message); } var f = test; f('hello world'); 你也可以直接将函数申明赋值给变量: var f = function(message){ alert(message); }; f('hello world'); 在这种情况下,函数申明

浅谈js中test()函数在正则中的使用

test() 方法用于检测一个字符串是否匹配某个模式. 返回一个 Boolean 值,它指出在被查找的字符串中是否匹配给出的正则表达式. regexp.test(str) 参数 regexp 必选项.包含正则表达式模式或可用标志的正则表达式对象. str 必选项.要在其上测试查找的字符串. 说明 test 方法检查字符串是否与给出的正则表达式模式相匹配,如果是则返回 true,否则就返回 false. 每个正则表达式都有一个 lastIndex 属性,用于记录上一次匹配结束的位置. var

浅谈C++中虚函数实现原理揭秘

编译器到底做了什么实现的虚函数的晚绑定呢?我们来探个究竟. 编译器对每个包含虚函数的类创建一个表(称为V TA B L E).在V TA B L E中,编译器放置特定类的虚函数地址.在每个带有虚函数的类中,编译器秘密地置一指针,称为v p o i n t e r(缩写为V P T R),指向这个对象的V TA B L E.通过基类指针做虚函数调用时(也就是做多态调用时),编译器静态地插入取得这个V P T R,并在V TA B L E表中查找函数地址的代码,这样就能调用正确的函数使晚捆绑发生

原文 https://www.zhangshengrong.com/p/On1vqnDyXy/

正文到此结束