为什么要指定swagger的api参数
api的参数有多种类型:
query 参数,如 /users"" src="/UploadFiles/2021-04-08/20200707091646.jpg">
难点
对 Django REST Swagger < 2 的版本,要指定swagger的api参数非常容易,只要将相关说明以特定格式和yaml格式写在相应api的视图函数的文档字符串(DocStrings)里,swagger就会自动渲染到文档中。比如这样的格式:
def cancel(self, request, id): """ desc: 取消任务,进行中的参与者得到报酬 ret: msg err: 404页面/msg input: - name: id desc: 任务id type: string required: true location: path """
但是在2.0版本之后,Django REST Swagger废弃了对yaml文档字符串的支持,不会渲染出任何内容。
一种解决方案
在Django REST framework基于类的api视图中定义filter_class过滤出模型(models)的特定字段,swagger会根据这些字段来渲染。
from django_filters.rest_framework.filterset import FilterSet class ProductFilter(FilterSet): class Meta(object): models = models.Product fields = ( 'name', 'category', 'id', ) class PurchasedProductsList(generics.ListAPIView): """ Return a list of all the products that the authenticated user has ever purchased, with optional filtering. """ model = Product serializer_class = ProductSerializer filter_class = ProductFilter def get_queryset(self): user = self.request.user return user.purchase_set.all()
这个解决方法只解决了一半问题,只能用在面向模型的api,只能过滤模型的一些字段,而且api参数名与模型字段名不一致时还要额外处理。
启发
查阅Django REST Swagger的文档,Advanced Usage提到,基于类的文档api视图是这样的:
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() schema = generator.get_schema(request=request) return Response(schema)
说明文档是根据schema变量来渲染的,所以可以通过重载schema变量,利用yaml包解析出api视图函数的文档字符串中的参数定义赋值给schema变量。
更好的解决方法
创建schema_view.py:
from django.utils.six.moves.urllib import parse as urlparse from rest_framework.schemas import AutoSchema import yaml import coreapi from rest_framework_swagger.views import get_swagger_view class CustomSchema(AutoSchema): def get_link(self, path, method, base_url): view = self.view method_name = getattr(view, 'action', method.lower()) method_docstring = getattr(view, method_name, None).__doc__ _method_desc = '' fields = self.get_path_fields(path, method) try: a = method_docstring.split('---') except: fields += self.get_serializer_fields(path, method) else: yaml_doc = None if method_docstring: try: yaml_doc = yaml.load(a[1]) except: yaml_doc = None # Extract schema information from yaml if yaml_doc and type(yaml_doc) != str: _desc = yaml_doc.get('desc', '') _ret = yaml_doc.get('ret', '') _err = yaml_doc.get('err', '') _method_desc = _desc + '\n<br/>' + 'return: ' + _ret + '<br/>' + 'error: ' + _err params = yaml_doc.get('input', []) for i in params: _name = i.get('name') _desc = i.get('desc') _required = i.get('required', False) _type = i.get('type', 'string') _location = i.get('location', 'form') field = coreapi.Field( name=_name, location=_location, required=_required, description=_desc, type=_type ) fields.append(field) else: _method_desc = a[0] fields += self.get_serializer_fields(path, method) fields += self.get_pagination_fields(path, method) fields += self.get_filter_fields(path, method) manual_fields = self.get_manual_fields(path, method) fields = self.update_fields(fields, manual_fields) if fields and any([field.location in ('form', 'body') for field in fields]): encoding = self.get_encoding(path, method) else: encoding = None if base_url and path.startswith('/'): path = path[1:] return coreapi.Link( url=urlparse.urljoin(base_url, path), action=method.lower(), encoding=encoding, fields=fields, description=_method_desc ) schema_view = get_swagger_view(title='API')
urls.py中指向schema_view:
from .schema_view import schema_view urlpatterns = [ url(r'^v1/api/', include([ url(r'^doc/', schema_view), ])),
然后在需要指定api参数的视图类(如APIView或ModelViewSet)中重载schema:
schema = CustomSchema()
以上这篇Django REST Swagger实现指定api参数就是小编分享给大家的全部内容了,希望能给大家一个参考,也希望大家多多支持。
RTX 5090要首发 性能要翻倍!三星展示GDDR7显存
三星在GTC上展示了专为下一代游戏GPU设计的GDDR7内存。
首次推出的GDDR7内存模块密度为16GB,每个模块容量为2GB。其速度预设为32 Gbps(PAM3),但也可以降至28 Gbps,以提高产量和初始阶段的整体性能和成本效益。
据三星表示,GDDR7内存的能效将提高20%,同时工作电压仅为1.1V,低于标准的1.2V。通过采用更新的封装材料和优化的电路设计,使得在高速运行时的发热量降低,GDDR7的热阻比GDDR6降低了70%。
更新日志
- 群星《前途海量 电影原声专辑》[FLAC/分轨][227.78MB]
- 张信哲.1992-知道新曲与精丫巨石】【WAV+CUE】
- 王翠玲.1995-ANGEL【新艺宝】【WAV+CUE】
- 景冈山.1996-我的眼里只有你【大地唱片】【WAV+CUE】
- 群星《八戒 电影原声带》[320K/MP3][188.97MB]
- 群星《我的阿勒泰 影视原声带》[320K/MP3][139.47MB]
- 纪钧瀚《胎教古典音乐 钢琴与大提琴的沉浸时光》[320K/MP3][148.91MB]
- 刘雅丽.2001-丽花皇后·EMI精选王【EMI百代】【FLAC分轨】
- 齐秦.1994-黄金十年1981-1990CHINA.TOUR.LIVE精丫上华】【WAV+CUE】
- 群星.2008-本色·百代音乐人创作专辑【EMI百代】【WAV+CUE】
- 群星.2001-同步过冬AVCD【环球】【WAV+CUE】
- 群星.2020-同步过冬2020冀待晴空【环球】【WAV+CUE】
- 沈雁.1986-四季(2012梦田复刻版)【白云唱片】【WAV+CUE】
- 纪钧瀚《胎教古典音乐 钢琴与大提琴的沉浸时光》[FLAC/分轨][257.88MB]
- 《国语老歌 怀旧篇 3CD》[WAV/分轨][1.6GB]