时间:2021-05-22
介绍
我们在实际的开发工作中需要将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 SchemaGeneratorfrom rest_framework.schemas.coreapi import LinkNode, insert_intofrom rest_framework.renderers import *from rest_framework_swagger import renderersfrom rest_framework.response import Responsefrom rest_framework.decorators import APIViewfrom rest_framework.permissions import AllowAny,IsAuthenticated,IsAuthenticatedOrReadOnlyfrom django.http import JsonResponseclass 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 adminfrom rest_framework import routersfrom django.conf.urls import url,include# 下面是刚才自定义的schemafrom app.schema_view import SwaggerSchemaView# 自定义接口from app.recommend import CustomViewrouter = 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以及自定义参数问题就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家多多支持。
声明:本页内容来源网络,仅供用户参考;我单位不保证亦不表示资料全面及准确无误,也不保证亦不表示这些资料为最新信息,如因任何原因,本网内容或者用户因倚赖本网内容造成任何损失或损害,我单位将不会负任何法律责任。如涉及版权问题,请提交至online#300.cn邮箱联系删除。
前言我们在django-rest-framework自定义swagger文章中编写了接口,调通了接口文档.接口文档可以直接填写参数进行请求,接下来的问题是如何接
日常开发,我们可能会为了安全问题,保证第三方无法通过伪造返回报文欺骗前端,需要在返回报文中添加自定义参数,用于验证身份,后端添加自定义参数,前端校验自定义参数通
1.需要注意的问题mvc框架的处理日期问题@ResponseBody响应对象是自定义对象,响应不是json@ResopnseBody响应自定义对象时,日期为是l
创建新项目,及应用django-adminstartprojectmyprojcdmyprojpythonmanage.pystartappmyapp自定义Us
提供两种方式的分类树格式,表格和下拉框形式的树形结构可以自定义表格和下拉框的样式,自定义以哪一列的参数为格式化数据,自定义层级关系参数,自定义表格列名称,也可以