首页
学习
活动
专区
圈层
工具
发布

Django集成Swagger全指南:两种实现方案详解

一、前言概述在前后端分离开发中,API 文档的重要性不言而喻。Swagger(现更名为 OpenAPI)作为主流的 API 文档生成工具,能自动生成交互式文档,极大提升开发效率。...Swagger UI,支持多种主题可自定义文档样式和内容支持隐藏指定字段、添加额外参数等高级功能安装步骤安装pip install -U drf-yasg配置settings.py:在 INSTALLED_APPS...", "DESCRIPTION": "火星信息平台接口文档", "VERSION": "1.0.0", "SERVE_INCLUDE_SCHEMA": False, # 不在文档中包含...四、drf-spectacular 高级使用技巧字段注释文档描述优先从序列化器 / 模型的 help_text 提取:class SystemPost(models.Model): id = models.BigAutoField...True, help_text="岗位ID") code = models.CharField( max_length=64, help_text="岗位编码", # 会显示在文档中

38110
  • 您找到你想要的搜索结果了吗?
    是的
    没有找到

    第 16 篇:别再手动管理接口文档了

    可以看到内容大体上是正确的,接口基本上都罗列了出来,但是仔细检查各个接口的内容,就会发现一些问题: GET /api-version/test/ 这个接口是我们用来测试的,不希望它显示在文档里。...例如我们可以看到 GET /posts/{id}/ 这个接口的响应参数,其中大部分有中文信息的描述,我们可以推断,这些说明都是 drf-yasg 自动从定义在 Post 模型各字段的 verbose_name...其中 toc 和 body_html 因为不是 Post 中定义的字段,所以 drf-yasg 无法知道关于这两个字段的说明。 drf-yasg 是如何知道这个接口会返回哪些响应参数的呢?...原理是 drf-yasg 会尝试去解析接口对应的序列化器(Serializer),从序列化器中提取出对应的请求和响应字段(如果序列化器中找不到,它会进一步去序列化器关联的模型中找),因此我们就可以给序列化器中定义的字段添加说明信息...会从这些属性去解析接口支持的参数,例如视图集设置了 filterset_class = PostFilter 和 pagination_class=PageNumberPagination(虽然不在视图集中显示定义

    2.3K20

    DRF自动生成OpenAPI文档

    DRF自动生成OpenAPI文档 API schemas是非常有用的,可以帮助我们生成接口文档以及可与API交互的动态客户端。...在这里我们使用drf-spectacular这个第三方库来自动生成OpenAPI schemas. drf-spectacular 安装,配置步骤可以参考drf-spectacular文档,下面简单的给出步骤...安装和配置 使用 经过上面的基本配置,我们现在访问api/schema/swagger-ui/来查看swagger-ui风格的文档,如下所示: 当你点击schema的时候,就会显示响应字段的描述...,description是来自于序列化器的文档字符串,而各个字段的title是来自于字段的label,带有*的意味着是必传的字段,除此之外,字段的其它描述是直接取自序列化器字段中的参数。...另外,对于该接口的描述也是直接来自文档字符串的内容。

    3.2K20

    Django Swagger文档库drf-spectacular

    你必须提供一个兼容OpenAPI3的字典,该字典可以直接翻译成YAML。...methods:检查extend_schema中特殊的方法,默认匹配所有 versions:检查extend_schema中特殊的API版本,默认匹配所有 example:将请求/响应示例附加到操作中.../authentication.py文件中可以看到,这个的作用就是在文档中显示什么样认证页面 对于认证页面的显示,主要是根据settings.py配置中的 REST_FRAMEWORK = {...,因此页面就会显示两种认证方式 BUG 目前使用中存在一个BUG,就是对于read_only字段,按照我们的理解就是在查询请求是返回给客户端,而创建时在请求体中不需要包含。...在默认生成的swagger界面上,我们看到的情况与理解的一样,对于JSON参数的请求是没有问题的,我们只需要输入必填的字段就可以了,但是如果是form-data参数,虽然显示的依然不包含read_only

    2.6K20

    第 9 篇:实现分类、标签、归档日期接口

    (Post)的创建日期(已去重),日期都是 Python 的 date 对象,精确到月份,降序排列。...注意到红框圈出部分,django-rest-framework API 交互后台会识别到额外定义的 action 并将它们展示出来,点击就可以进入到相应的 API 页面。...from .models import Post class PostFilter(drf_filters.FilterSet): created_year = drf_filters.NumberFilter...category,tags 两个过滤字段因为是 Post 模型中定义的字段,因此 django-filter 可以自动推断其过滤规则,只需要在 Meta.fields 中声明即可。...由于这两个字段在 Post 中没有定义,Post 记录时间的字段为 created_time,因此我们需要显示地定义查询规则,定义的规则是: 查询参数名 = 查询参数值的类型(查询的模型字段,查询表达式

    3.6K30

    第 11 篇:基于 drf-haystack 的文章搜索接口

    先来定义序列化器,粗略过一遍 drf-haystack 官方文档[3],依葫芦画瓢创建文章(Post) 的 Serializer blog/serializers.py from drf_haystack.serializers...需要高亮的其实是 2 个字段,一个是 title、一个是 body。而 body 我们不需要完整的内容,只需要摘出其中一部分作为搜索结果的摘要即可。...自定义序列化字段其实非常的简单,基本流程分两步走: 从 drf 官方提供的序列化字段中找一个数据类型最为接近的作为父类。 重写 to_representation 方法,加入自己的序列化逻辑。...对象,这个对象就是视图中的 HTTP 请求对象,但是因为 django 中 request 对象无法像 flask 那样从全局获取,因此 drf 在视图中将其保存在了序列化器和序列化字段的 context...为 /api/search/?

    2.2K20

    Vue+Django2.0 REST framework 打造前后端分离的生鲜电商项目(五)商品列表页

    在views_base中,我被 JsonResponse,HttpResponse这两个模块之间的有什么不同所引起好奇心,都是返回字符串,一个可以返回json,而另一个需要添加一些设置才能返回json。...写views 在apps/goods下新建serializer.py文件(drf中的serializer.py等同于django中的forms.py) 1 from rest_framework import...(昵称),而drf在找的是AbstractUser的username字段(用户名),没找到所以报错 解决方法:将UserProfile表中的__str__方法改成返回username: 1 def...__str__(self): 2 return self.username 三、drf实现商品列表页的功能 1.ModelSerializer(相当于django中的modelform...它支持解析HTTP方法以外的内容POST,这意味着你可以访问内容PUT和PATCH请求。 它支持REST框架的灵活请求解析,而不仅仅是支持表单数据。

    5.2K61

    DjangoRestFramework,序列化组件、视图组件

    给我们做了一个更牛逼的序列化组件,功能更强大,而且不仅仅能做序列化,还能做其他的事情,所以呢,做api的时候,我们还是用drf提供的序列化组件。...的Response如果返回的是drf序列化之后的数据,那么客户端拿到的是一个有格式的数据,不再是一行显示了   看效果: ?...=True,则对应的serializers.DateTimeField中将默认使用属性read_only=True,如果不想使用此行为,需要显示对该字段进行声明: class CommentSerializer...1.read_only read_only=True表示该字段为只读字段,即对应字段只用于序列化时(输出),而在反序列化时(创建对象)不使用该字段。默认值为False。...10.help_text 一个文本字串,可用作HTML表单字段或其他描述性元素中字段的描述。

    3K20

    Django+Vue开发生鲜电商平台之7.用户登录和注册功能

    2.DRF实现发送短信验证码接口 需要在DRF中接入短信验证码发送。...说明: 因为接口请求需要用POST方法,因此开始直接使用GET方法会失败,DRF提供了在页面直接用POST方法发送数据的功能,这对以后的测试提供了极大的方便。...显然,对于多个字段的验证,如果某一个字段验证失败,则提示该字段的错误信息,如果多个字段验证失败,则将这些字段的错误信息都显示出来。...字段,但是在validate(attrs)又将其删去,导致在序列化时找不到code字段,因此出错,这是需要将字段的write_only设置True,以确保在更新或创建实例时可以使用该字段,但是在序列化表示形式时不包括该字段...这里传递了注册需要用到的3个字段,并且使用了register接口,在api.js中定义修改如下: //注册 export const register = parmas => { return axios.post

    5.2K20

    简化 Django 开发的八个 Python 包 | Linux 中国

    ◈   describe_form 输出模型的表单定义,可以粘贴到   forms.py 文件中。(需要注意的是,这种方法创建的是普通 Django 表单,而不是模型表单。)...,该方法自动更新   created 和   modified 字段的值。...安装了 django-environ 之后,在项目的根目录创建一个 .env 文件,用这个文件去定义那些随环境不同而不同的变量,或者需要保密的变量。...处理 Django REST 框架的用户认证:django-rest-auth  如果 Django 开发中涉及到对外提供 API,你很可能用到了 Django REST Framework[22](DRF...你只需要安装 Django REST Swagger,把它添加到 Django 项目的已安装应用中,然后在 urls.py 中添加 Swagger 的视图和 URL 模式就可以了,剩下的事情交给 API

    3.7K20

    Python利用Django 构建Rest Api: 快速入门教程

    前言 在本篇中,我们将为大家介绍如何基于Python构建一个以Django Rest框架为特征的博客应用程序API服务,并且该API服务支持CRUD (Create-Read-Update-Delete...fields字段控制数据库数据的类型。在本例中,我们将暴露所有字段,包括id,这是Django的主键,由Django自动添加到所有数据库记录。 4、接下来,我们需要创建view。...正如Django有基于类的视图一样,DRF也有我们可以使用的通用视图。例如,本示例中,我们定义一个列出所有博客文章和一个文章内容详细视图以及更新文章内容的视图,脚本如下所示。...() serializer_class = serializers.PostSerializer 在脚本中,我们从DRF中导入基础视图类generics,以及我们的模型和序列化文件。...api/端点以JSON格式显示本篇示例添加的2篇博客文章。 3、接着访问http://127.0.0.1:8000/api/2/,您将查看到第二篇文章的详细内容。 ?

    6K20

    Django序列化器的简单使用

    在类中写需要序列化的字段,即需要序列化哪些字段就在类中写哪个字段。为使代码清晰、方便管理,我们可以新建一个ser.py 文件来存储序列化器的代码。...,默认False write_only 表明该字段仅用于反序列化输入,默认False required 表明该字段在反序列化时必须输入,默认True default 反序列化时使用的默认值 allow_null...表明该字段是否允许传入None,默认False validators 该字段使用的验证器 error_messages 包含错误编号与错误信息的字典 label 用于HTML展示API页面时,显示的字段名称...help_text 用于HTML展示API页面时,显示的字段帮助提示信息 2、创建Serializer对象 在定义好序列化器类之后,我们就可以创建序列化对象了。...序列化器的字段声明类似于我们前面使用过的表单系统。 开发restful api时,序列化器会帮我们把模型数据转换成字典。

    2K40

    django rest framework serializers解读

    form更强调对提交的表单进行一种验证,而serializer的field不仅在进行数据验证时起着至关重要的作用,在将数据进行序列化后返回也发挥着重要作用!...,而不应该由用户post过来,如果不设置read_only=True,那么验证的时候就会报错。...,如 label=’验证码’ help_text: 在指定字段增加一些提示文字,这两个字段作用于api页面比较有用 style: 说明字段的类型,这样看可能比较抽象,看下面例子: # 在api页面,...我们在mixins的博客中提及到,post请求对应create方法,而patch请求对应update方法,这里提到的create方法与update方法,是指mixins中特定类中的方法。...,我们在read_only提及到一个例子,订单号的生成,我们可以在这步生成一个订单号,然后添加到attrs这个字典中。

    2.2K10
    领券