DRF Swagger自定义的action文档参数实现 Posted July 04, 2018 ?...#Swagger 这里不讲 DRF(django rest framework) 和 DRS(django rest swagger) 如何结合使用, 在以上两个项目文档中都有相关文档。...描述工具), 这样后在Swagger上就可以根据相关的 Link 识别出所需的参数(Query或者Form)了。...但大多数我们往往需要根据特定的需求, 做一些自定义的接口, 比如使用的 api_view 装饰器定义的函数式视图, 或者使用DRF 中的 action 装饰器定义的自定义接口(在一些较早的DRF版本中为...这时候, swagger UI 上执行的时候, 就可以显示出来参数的表单了.
可以看到内容大体上是正确的,接口基本上都罗列了出来,但是仔细检查各个接口的内容,就会发现一些问题: GET /api-version/test/ 这个接口是我们用来测试的,不希望它显示在文档里。...drf-yasg 提供了一个 swagger_auto_schema 装饰器来装饰视图,只需要为装饰器设置 auto_shema=None 就可以让 drf-yasg 忽略掉被装饰的视图,具体用法如下:...因为 PostSearchView 继承自 HaystackViewSet,在代码中并没有显示地定义 retrieve 这个方法,而是从父类继承而来,所以我们借助 django 提供的辅助函数 method_decorator...会从这些属性去解析接口支持的参数,例如视图集设置了 filterset_class = PostFilter 和 pagination_class=PageNumberPagination(虽然不在视图集中显示定义...,但在全局进行了配置),在解析 list_archive_dates 的参数时,drf-yasg 错误地解析到了从视图集继承来的 PostFilter 和 PageNumberPagination,所以就把这两个类中定义的参数也包含进文档了
上面列出的工具或多或少都需要花费一定时间去手动维护,在drf后端项目中可以利用其自带的Core API、第三方库Swagger以及更好的drf-yasg自动生成接口文档 2、Core API生成接口文档...2.5 补充说明 1、上面访问到的接口文档,可以按照右边的指引通过安装coreapi-cli,通过命令行操作访问接口文档 2、对于视图集ViewSet中的retrieve名称,在接口文档中叫做read...所有操作均已折叠 list 列出所有操作 full 扩展所有操作 'DOC_EXPANSION': None, # 是否显示请求标头 'SHOW_REQUEST_HEADERS...': True, # 切换使用Django Auth作为身份验证机制 将其设置为True将会在Swagger UI上显示一个登录/注销按钮,并将csrf_tokens发布到API 'USE_SESSION_AUTH...: 2.2, 3.0, 3.1 Python: 3.6, 3.7, 3.8, 3.9 4.2 安装drf-yasg库 在操作下面的步骤前请将第3节swagger相关内容全部注释或还原 pip3 install
在使用DRF的时候,通常的文档有:默认文档RestFrameWork、CoreAPI、Swagger,Swagger是最流行的API文档库,在绝大多数服务端开发中都有用到,之前我们使用了CoreAPI来生成文档...中排除操作 operation:手动覆盖自动发现将生成的内容。.../authentication.py文件中可以看到,这个的作用就是在文档中显示什么样认证页面 对于认证页面的显示,主要是根据settings.py配置中的 REST_FRAMEWORK = {...可以识别 DEFAULT_AUTHENTICATION_CLASSES 下的认证方式,就会在文档登录页面上显示对应的认证方式,这里我们有自定义的认证方式,如果需要显示,要做一下适配: from drf_spectacular.extensions...在默认生成的swagger界面上,我们看到的情况与理解的一样,对于JSON参数的请求是没有问题的,我们只需要输入必填的字段就可以了,但是如果是form-data参数,虽然显示的依然不包含read_only
action 装饰器通常用于在视图集中添加额外的接口实现。例如这里我们已有了 PostViewSet 视图集,标准的 list 实现了获取文章资源列表的逻辑。...现在,侧边栏所需要的数据接口就开发完成了,接下来实现返回某一分类、标签或者归档日期下的文章列表接口。 在 使用视图集简化代码 我们开发了获取全部文章的接口。...事实上,分类、标签或者归档日期文章列表的 API,本质上还是返回一个文章列表资源,只不过比首页 API 返回的文章列表资源多了个“过滤”,只过滤出了指定的部分文章而已。...Serializer 非常类似。...由于这两个字段在 Post 中没有定义,Post 记录时间的字段为 created_time,因此我们需要显示地定义查询规则,定义的规则是: 查询参数名 = 查询参数值的类型(查询的模型字段,查询表达式
在DRF官方教程的学习过程中,一个很明显的感受是框架在不断地进行封装,我们自己写框架/工具/脚本/平台也可以模仿模仿,先完成底层代码,再做多层封装,让使用者很容易就上手操作。...ViewSets 先看看之前在给User模型创建Endpoint时,我们新增的2个视图: class UserList(generics.ListAPIView): queryset = User.objects.all...可以把它们合成一个视图。 set是集合的意思,ViewSets就是视图集合。...,默认为GET请求,如果想改为POST请求,可以添加参数methods,它的源码如下: def action(methods=None, detail=None, url_path=None, url_name...Routers 使用ViewSet的一大好处是可以自动配置路由,DRF提供了rest_framework.routers: ?
DRF自动生成OpenAPI文档 API schemas是非常有用的,可以帮助我们生成接口文档以及可与API交互的动态客户端。...在这里我们使用drf-spectacular这个第三方库来自动生成OpenAPI schemas. drf-spectacular 安装,配置步骤可以参考drf-spectacular文档,下面简单的给出步骤...安装和配置 使用 经过上面的基本配置,我们现在访问api/schema/swagger-ui/来查看swagger-ui风格的文档,如下所示: 当你点击schema的时候,就会显示响应字段的描述...我们需要手动修改,如下所示: 手动在代码中加入以下内容: class BookView(GenericAPIView): """删改查视图""" queryset = BookInfo.objects.all...在视图集中使用 对于视图集而言,可以使用@extend_schema_view装饰器来直接装饰类。
DRF视图和常用功能 DRF视图 DRF视图类介绍 在DRF框架中提供了众多的通用视图基类与扩展类,以简化视图的编写。...View:Django默认的视图基类,负责将视图连接到URL,HTTP请求方法的基本调度,之前写类视图一般都用这个。...APIView:DRF提供的所有视图的基类,继承View并扩展,具备了身份认证、权限检查、流量控制等功能。...常用属性: request.data:返回POST提交的数据,与request.POST类似 request.query_params:返回GET URL参数,与request.GET类似 浏览器get...,实现以下功能: 增加queryset属性,指定操作的数据,不用再将数据传给序列化器,会自动实现。
接下来,在本篇文章,介绍的就是基于Python3+Django3下,如何接入Swagger框架,并且实现Swagger接口文档的自动生成。 2....Swagger优势: 1)Swagger可生成一个具有互动性的API控制台,开发者可快速学习和尝试API 2)Swagger支持不同客户端SDK代码,用于不同平台上(Java、Python、...)的实现...Django项目配置 1、在开始之前,我们先创建一个项目操作目录和隔离环境,具体操作如下: # 创建项目目录 mkdir django_swagger cd django_swagger # 创建隔离开发环境...在django 3.0中已经不支持该库了,取而代之的是全新的第三方drf-yasg库。...4、Swagger除了可以即时生成接口文档以外,还可以用于在线做一些接口功能测试,如下所示。 ? ? 5、在Swagger中还可以查看到在model定义的各字段类型及参数说明。 ?
' } 在 LearnDjango/urls.py添加 from django.contrib import admin from django.urls import path, include, re_path...添加注释 单一方法的视图 直接给视图类添加注释 多个方法的视图 class ProjectsListCreateViewSet(ListCreateAPIView): """ get: 返回所有项目信息...使用drf-yasg 支持swagger $ pip install drf-yasg 添加到 INSTALLED_APPS中 INSTALLED_APPS = [ ......'drf_yasg' ... ] 在 LearnDjango/urls.py中添加以下部分 from django.contrib import admin from django.urls import...访问 http://127.0.0.1:8000/swagger.yaml 会自动下载一份yaml文件 ? 访问 http://127.0.0.1:8000/swagger/ ?
视图集只在使用as_view()方法的时候,才会将action动作与具体请求方式对应上。...APIView基本类似,提供了身份认证、权限校验、流量管理等。..."""经过上面的处理,我们就已经把所有视图方法写在一个类中了,但是继承父类有点多 所以,drf里面提供了模型视图集[ModelViewSet],可以一次性提供5个api接口的方法 最后,def还提供了只读模型视图集...(self): """在视图集中视图对象下面会新增一个action属性,用于获取视图方法名""" if BookInfo.action == "get_top_3":...="url路径,不填写则默认使用方法名") @action(methods=["get","put"],detail=True,url_path="getTop") def get_top
关于swagger Swagger能成为最受欢迎的REST APIs文档生成工具之一,有以下几个原因: Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。...Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。 Swagger 文件可以在许多不同的平台上从代码注释中自动生成。 Swagger 有一个强大的社区,里面有许多强悍的贡献者。...下面就实战django rest swagger为drf生成api接口文档 环境 Python3.6 Django1.11 django-rest-swagger djangorestframework...serializers.HyperlinkedModelSerializer): class Meta: model =Group fields = "__all__" 配置api/views.py # 视图...登录 url(r'^api-auth/',include('rest_framework.urls',namespace='rest_framework')) ] 最终效果 drf自带的接口UI
目录 DRF 路由组件 路由是如何映射的?...继承ModelViewSet,路由写法 自己配路由的映射 自动生成路由 action装饰器 继承APIView+ViewSetMixin使用装饰器 路由router形成URL的方式 DRF 路由组件...路由的配置上篇我们提到了一点自动配置,对于继承了视图集ViewSet就可以自动生成路由,当然了也可以选择手动版自己配,可以使用action装饰器来指定方法等操作,屁话不多说如下: REST framework...带id url_path:地址,地址如果不写,默认已方法名为地址 url_name:起别名 继承APIView+ViewSetMixin使用装饰器 from rest_framework.decorators...DefaultRouter会多附带一个默认的API根视图,返回一个包含所有列表视图的超链接响应数据 总结 路由的写法有三种: 手动配置:path('books/', views.BookDetailView.as_view
framework来编写RESTful风格的API 特性: 强大的序列化器,可以高效的进行序列化和反序列化操作。...极丰富的类视图,Mixin扩展视图,ViewSet视图 提供了直观的web api界面 支持多种身份认证和权限认证 强大的排序,过滤,分页,搜索,限流等功能。...django-filter https://django-filter.readthedocs.io/en/main/ django-filter可以方便的进行内容的过滤,在搜索栏输入内容搜索的时候会用到...比如进行模糊查询 drf-yasg https://drf-yasg.readthedocs.io/en/stable/ drf-yasg根据代码生成swagger页面,方便后面的调试 Faker https...'formatters': { # 日志信息显示的格式 'verbose': { 'format': '%(levelname)s %(asctime
它可以自动帮我们提取接口中的信息,从而形成接口文档,而且内容十分详细,再也不用为写接口文档而心烦了 这个库主要实现了3个目标 从DRF中提取更多的schema信息 提供灵活性,使schema在现实世界中可用...(3.10, 3.11, 3.12) 安装 使用pip命令安装 pip install drf-spectacular 然后在settings.py的INSTALLED_APPS安装drf-spectacular...swagger接口文档,但是我们点开接口会发现没有任何内容信息 所以我们还需要在view视图中,使用装饰器@extend_schema来制定接口文档中的接口信息 我们先来看下装饰器extend_schema...中排除操作 operation:手动覆盖自动发现将生成的内容。...extensions:规范扩展 最后我们在登录视图的post方法中添加@extend_schema装饰器,传入上面你所需要的字段,就可以了 @extend_schema( summary
DRF框架中的英文单词 1. prefix/'prifɪks/前缀,我们在路由配置的时候经常看见这个单词。在flask中,我们可以在设置url的时候为了区别视图,在类似功能的url全部加一个前缀。...Errorhandling错误处理,在Restful设计风格中,如果状态码是4xx,我们就应该返回错误的信息,通常来说是下面这个样子,但是不唯一: {error:""} 7...PATCH这个操作在现在基本上是不用的,但是我们了解一下,path只是将更改的内容发送,put将更改后所有的内容都发送过去。这个在网上说法不一,先按这种理解,毕竟没人用这种操作方式了,而是用put。...20. model/'mɑdl/模型,我们在很多的时候都用到了这个单词,在DRF框架我们在下面的情况中用到了这个单词。指明该序列化器处理的数据字段从模型类BookInfo参考生成。...27. params/ˌpærəˈm/参数,这个大家不陌生,经常看见。 28. generic/dʒə'nɛrɪk/类的,是形容词。视图的两个基类中GenericAPIView就有这个单词。
在Django REST Framework中,视图是处理HTTP请求和响应的核心组件。视图接收HTTP请求,然后根据请求的方法(GET,POST,PUT等)执行相应的操作,并返回HTTP响应。...DRF视图可以是函数视图或基于类的视图。函数视图类似于Django中的函数视图,它接收一个request对象并返回一个响应。...基于类的视图是DRF中的主要视图类型,它继承自DRF提供的基类,并提供了一些常见的功能,例如身份验证,权限控制和序列化器的使用。...在perform_create()方法中,我们保存了反序列化的数据。在DRF中,还有许多其他视图类型可用。...以下是一些常用的视图类型:ListAPIView:提供一个只读列表视图,显示一个查询集的序列化结果。RetrieveAPIView:提供一个只读详情视图,显示一个对象的序列化结果。
url路由到视图主要还是利用django的dispatcher路由系统(可以参考我的另一篇关于django url dispatcher详解),但是rest_framework还在django路由的基础上...类型:正则字符串 viewset视图类。继承了ViewSetMinix类。类型:is-a ViewSetMinix basename 用于生成url的url名称。...,destroy,partial_update),单资源的操作路由 一般list (list, create) , 资源集的操作路由 动态detail (通过@action装饰器), 单资源的额外操作...做视图路由了。...使用SimpleRouter对于常用的action名是约定俗成的,所以要遵照这些著名的action名,定义符合的操作资源逻辑。
自动生成api文档(不管是函数视图还是类视图都能显示) 1.安装rest_framework_swagger库 pip install django-rest-swagger 2.在项目下的 urls.py...='API文档') urlpatterns += [ path(r'docs/', schema_view), ] 3.在创建的django项目下的settings中加入如下: INSTALLED_APPS...5、DRF访问接口自带的界面如下: ? ?...\a1\Lib\site-packages\rest_framework_swagger\templates\rest_framework_swagger\index.html python环境下的rest_framework_swagger...包并不能正常的引入, 那么这个时候首先将你的pip升级 python -m pip install --upgrade pip 升级到了最新的pip之后再执行 pip install rest_framework_swagger
,不能合并 有相同的get方法 两个类视图所对应的url地址不一致 再次优化 优化思路:使用动作来触发,而不是请求方法 from rest_framework import viewsets viewsets...Django中 View DRF中 APIView GenericAPIView mixins扩展类 CreateAPIView(合并拓展类) 视图集 action和请求方法的映射 ViewSet GenericViewSet...if url_path else func....参数用于指定该动作支持的请求方法,默认为get detail用于指定该动作要处理的是否为详情资源对象「url是否需要传递pk值」 在 url.py中添加 path('project/names/', views.ProjectsViewSet.as_view...添加 url_path和 url_name @action(methods=['get'], detail=False, url_path='nm', url_name='url_name') ?
领取专属 10元无门槛券
手把手带您无忧上云