Django自动生成Swagger接口文档 —— Python

1. 前言

当接口开发完成,紧接着需要编写接口文档。传统的接口文档通常都是使用Word或者一些接口文档管理平台进行编写,但此类接口文档维护更新比较麻烦,每次接口有变更,需要手动修改接口文档。在实际的工作中,经常会遇到:“前端抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新”。为了解决这个问题,业界推出了一个Swagger框架来管理接口文档,实现接口文档的自动更新。

采用Swagger框架来管理接口文档,常用于在微服务架构设计或者Java的后端服务工程中。这也造成了很多读者误认为Swagger只是Java语言下的一个框架,其实并不是的,Swagger除了能应用在Java语言的工程中,也同时适用于在其它语言下,比如Python。接下来,在本篇文章,介绍的就是基于Python3+Django3下,如何接入Swagger框架,并且实现Swagger接口文档的自动生成。

2. Swagger介绍

Swagger:它是一款RESTFUL接口的文档在线自动生成+功能测试并集规范于一体的工具框架,可用于生成、描述、调用和可视化RESTful风格的Web服务。总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新。当接口有变动时,对应的接口文档也会自动更新生成。

例如:接口测试站点(http://httpbin.org/#/),也是利用Swagger来生成接口文档的。

Swagger优势: 1)Swagger可生成一个具有互动性的API控制台,开发者可快速学习和尝试API 2)Swagger支持不同客户端SDK代码,用于不同平台上(Java、Python、...)的实现 3)Swagger可在不同的平台上从代码注释中自动生成 4)Swagger社区活跃,里面有许多强悍的贡献者

3. Django项目配置

1、在开始之前,我们先创建一个项目操作目录和隔离环境,具体操作如下:

# 创建项目目录
mkdir django_swagger
cd django_swagger# 创建隔离开发环境
python3 -m venv env
source env/bin/activate​​

2、安装django相关库

​​(env) ➜ pip install django
(env) ➜ pip install djangorestframework

3、创建django项目和app

​
# 创建django项目和app
django-admin startproject drf_swagger
cd drf_swagger
django-admin startapp api​

需要注意的是,本篇文章示例,是基于Python3及Django当前最新库来进行的。

​
(env) ➜  pip list | grep django
Django               3.0.1
django-crispy-forms  1.8.1
django-formtools     2.2
django-import-export 2.0
django-reversion     3.0.5
djangorestframework  3.11.0

到此,我们已经准备好了django基础环境和生成好了项目结构。

4. Django接入Swagger

网上很多资料在介绍Django接入Swagger方法时,都是基于django-rest-swagger库进行讲解的,都殊不知,从2019年6月份开始,官方已经废弃了该库,在django 3.0中已经不支持该库了,取而代之的是全新的第三方drf-yasg库。

GitHub地址:

https://github.com/marcgibbons/django-rest-swagger

所以本文也是基于drf-yasg库来实现在Django3中接入Swagger框架的。

1、安装drf-yasg库

​pip install -U drf-yasg

GitHub项目地址:

https://github.com/axnsan12/drf-yasg

2、修改项目settings.py文件,添加api和drf_yasg。

​
# Application definitionINSTALLED_APPS = ['django.contrib.admin','django.contrib.auth','django.contrib.contenttypes','django.contrib.sessions','django.contrib.messages','django.contrib.staticfiles','rest_framework','drf_yasg','api',
]​

3、修改api/models.py,此处定义了一个添加接口的model模型(为了方便演示)

​from django.db import modelsclass APIInfo(models.Model):api_name = models.CharField(max_length=32, verbose_name="接口名称", default="请输入接口名称")# 接口描述api_describe = models.TextField(max_length=255, verbose_name="接口描述", default="请输入接口描述")# 接口负责人api_manager = models.CharField(max_length=11, verbose_name="接口负责人", default="请输入接口负责人名字")# 创建时间create_time = models.DateTimeField(auto_now_add=True, verbose_name="创建时间")# 修改时间update_time = models.DateTimeField(auto_now=True, blank=True, null=True, verbose_name="修改时间")class Meta:db_table = 'api_info'# 设置表名,默认表名是:应用名称_模型类名# 带有应用名的表名太长了verbose_name = '接口列表'verbose_name_plural = "接口列表"def __str__(self):return self.api_name​

4、修改api/admin.py,将model注册到后台,方便在管理后台添加接口记录。

​from django.contrib import admin
from . models import APIInfoadmin.site.register(APIInfo)​

5、新建api/serializers.py文件,代码内容如下:

​from rest_framework import serializers
from api.models import APIInfoclass APIInfoSerializer(serializers.HyperlinkedModelSerializer):class Meta:model = APIInfofields = "__all__"class APISerializer(serializers.ModelSerializer):class Meta:model = APIInfofields = "__all__"​

6、修改api/view.py视图文件,并在类中,添加注释如下所示(为了方便演示):

​
from rest_framework import viewsets
from rest_framework import generics
from . import models
from . import serializersclass APIList(generics.ListAPIView):"""查看接口列表"""queryset = models.APIInfo.objects.all()serializer_class = serializers.APISerializerclass APIDetail(generics.RetrieveAPIView):"""查看接口详细"""queryset = models.APIInfo.objects.all()serializer_class = serializers.APISerializerclass APIDetail(generics.RetrieveUpdateDestroyAPIView):"""更新接口内容"""queryset = models.APIInfo.objects.all()serializer_class = serializers.APISerializerclass APIInfoViewSet(viewsets.ModelViewSet):"""retrieve:返回一组(查)list:返回所有组(查)create:创建新组(增)delete:删除现有的一组(删)partial_update:更新现有组中的一个或多个字段(改:部分更改)update:更新一组(改:全部更改)"""queryset = models.APIInfo.objects.all()serializer_class = serializers.APIInfoSerializer​

7、修改项目url.py文件,进行路由配置。

​
from django.contrib import admin
from django.conf import settings
from django.urls import path,include
from rest_framework import routers, permissions
from drf_yasg.views import get_schema_view
from drf_yasg import openapifrom api import viewsrouter = routers.DefaultRouter()
router.register('api_info', views.APIInfoViewSet)schema_view = get_schema_view(openapi.Info(title="测试工程API",default_version='v1.0',description="测试工程接口文档",terms_of_service="https://www.cnblogs.com/jinjiangongzuoshi/",contact=openapi.Contact(email="狂师"),license=openapi.License(name="BSD License"),),public=True,permission_classes=(permissions.AllowAny,),
)urlpatterns = [path('admin/', admin.site.urls),# 配置django-rest-framwork API路由path('api/', include('api.urls')),path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),# 配置drf-yasg路由path('^swagger(?P<format>\.json|\.yaml)$', schema_view.without_ui(cache_timeout=0), name='schema-json'),path('swagger', schema_view.with_ui('swagger', cache_timeout=0), name='schema-swagger-ui'),path('redoc/', schema_view.with_ui('redoc', cache_timeout=0), name='schema-redoc'),]​

5. 执行数据同步、运行

1、上述一切配置完成后,开始进行数据库迁移、同步。

​​# 生成迁文件、执行同步
python manage.py makemigrations
python manage.py migrate​

2、创建后台管理员用户

代码语言:javascript

复制

python manage.py createsuperuser

3、运行服务

​python manage.py runserver

6. 验证效果

1、服务运行起来后,默认端口为8000,浏览器访问http://127.0.0.1:8000/redoc/,可查看redoc ui,效果如下所示。

2、点击左侧的api,展开各接口详细如下所示。

PS: ReDoc 是另一个 Swagger UI 工具。

3、继续访问http://127.0.0.1:8000/swagger,即可看到日常我们熟悉的Swagger接口文档界面了。

4、Swagger除了可以即时生成接口文档以外,还可以用于在线做一些接口功能测试,如下所示。

5、在Swagger中还可以查看到在model定义的各字段类型及参数说明。

到此,我们Django3接入Swagger已经完成了,更多swagger的功能使用请读者自行尝试。

本次分享到此结束,感谢大家的阅读!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/pingmian/43203.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

tomcat的优化和tomcat和nginx实现动静分离:

tomcat的优化 tomcat自身的优化 tomcat的并发处理能力不强。大项目不使用tomcat做为转发动态的中间件&#xff08;k8s集群&#xff0c;python&#xff0c;rubby&#xff09;&#xff0c;小项目会使用&#xff08;内部使用&#xff09;&#xff0c;动静分离。 优化tomcat的启动…

Python入门 2024/7/8

目录 数据容器 dict(字典&#xff0c;映射) 语法 定义字典字面量 定义字典变量 定义空字典 从字典中基于key获取value 字典的嵌套 字典的常用操作 新增元素 更新元素 删除元素 清空字典 获取全部的key 遍历字典 统计字典内的元素数量 练习 数据容器的通用操作…

linux环境下echo命令简单测试端口是否连通——筑梦之路

语法格式 echo > /dev/tcp/目标主机地址/端口号 示例 echo > /dev/tcp/example.com/80 当命令执行后&#xff0c;若端口是开放的&#xff0c;命令不会有任何输出并且会立即返回命令提示符&#xff1b;若端口未开放或连接失败&#xff0c;则可能由于网络问题、防火墙限…

在公司的业务杂记1之多选部门且主表没有部门字段(子表查询)

原型 1.新建&#xff0c;上传报告可多选部门 2.查询&#xff0c;可多选部门 数据库&#xff08;Postgresql&#xff09; 方式一 新增字段Jsonb&#xff1a; CREATE TABLE public.admin_report (admin_report_uuid uuid DEFAULT gen_random_uuid() NOT NULL,admin_report_tit…

java —— JSP 技术

一、JSP &#xff08;一&#xff09;前言 1、.jsp 与 .html 一样属于前端内容&#xff0c;创建在 WebContent 之下&#xff1b; 2、嵌套的 java 语句放置在<% %>里面&#xff1b; 3、嵌套 java 语句的三种语法&#xff1a; ① 脚本&#xff1a;<% java 代码 %>…

安全防御第三天(笔记持续更新)

1.接口类型以及作用 接口 --- 物理接口 三层口 --- 可以配置IP地址的接口 二层口 普通二层口 接口对 --- “透明网线” --- 可以将一个或者两个接口配置成为接口对&#xff0c;则 数据从一个接口进&#xff0c;将不需要查看MAC地址表&#xff0c;直接从另一个接口出&#xff1b…

机器学习模型运用在机器人上

机器学习模型在机器人技术中的应用非常广泛&#xff0c;涵盖了从简单的运动控制到复杂的认知和交互功能。以下是几种机器学习模型在机器人上的典型应用&#xff1a; 感知与识别&#xff1a; 计算机视觉&#xff1a;使用卷积神经网络&#xff08;CNNs&#xff09;识别和理解视觉…

汇川CodeSysPLC教程 Modbus变量编址

线圈&#xff1a;位变量&#xff0c;只有两种状态0和1。汇川PLC中包含Q区及SM区等变量。 寄存器&#xff1a;16位&#xff08;字&#xff09;变量&#xff0c;本PLC中包含M区及SD区等变量 说明&#xff1a; 汇川HMI的专用协议使用不同功能码&#xff1a;在访问SM时&#xff0c…

Python--并发编程--协程

概念 协程是轻量级的线程&#xff0c;它是程序员管理的并发机制&#xff0c;使得在一个线程中程序可以在多个函数之间交替运行。 Python中主要通过asyncio模块实现协程。 协程函数 用async修饰的函数 import asyncio# func为协程函数 async def func():await asyncio.slee…

Linux开发:进程间通过Unix Domain Socket传递文件描述符

Linux开发:进程间通过Unix Domain Socket传递数据-CSDN博客 介绍了通过UDS传递数据 实际上当需要传递大量的数据时,可以通过UDS直接传递文件描述符,这样接收文件描述符的一方,可以直接从传递过来的文件描述符读取数据 先举例说明: //uds_fd.hpp #pragma once #include &…

时尚品牌GOODBAI好人好事系列纪录片——Jupiter乐队的热血与梦想

时尚品牌GOODBAI推出的好人好事系列纪录片迎来了第二期&#xff0c;本期特别邀请了充满年轻活力的Jupiter乐队。纪录片通过真实的镜头&#xff0c;记录了他们在排练室中充满热血和灵感的创作过程&#xff0c;面对冷清观众席的微妙情绪&#xff0c;以及对未来的深刻思考和殷切期…

2024HW必修高危漏洞集合_v4.0

高危风险漏洞一直是企业网络安全防护的薄弱点&#xff0c;也成为HW攻防演练期间红队的重要突破口;每年 HW期间爆发了大量的高危风险漏洞成为红队突破网络边界防护的一把利器,很多企业因为这些高危漏洞而导致整个防御体系被突破、甚至靶标失守而遗憾出局。 HW 攻防演练在即&…

Vue的仓库是什么

Vue的仓库在广义上可以指存放Vue.js项目相关代码、组件、工具等资源的集合&#xff0c;这些资源可能托管在GitHub、GitLab等代码托管平台上。然而&#xff0c;在更具体的语境下&#xff0c;Vue的仓库可能指的是以下几个方面的内容&#xff1a; 1. Vue官方仓库 Vue.js核心库仓…

如何做一个透明度渐现且向上位移逐行出现的文字效果

前言 在这个夜黑风高的夜晚&#xff0c;你的眼睛已经开始有些疲惫。你的手指在键盘上轻轻地敲击着&#xff0c;仿佛在弹奏一首无声的夜曲。你的思绪在代码的海洋中飘荡&#xff0c;寻找着最后一行需要完成的代码。就在这时&#xff0c;你的老板走了过来&#xff0c;他的脸上带…

MySQL高级----InnoDB引擎

逻辑存储结构 表空间 表空间(ibd文件)&#xff0c;一个mysql实例可以对应多个表空间&#xff0c;用于存储记录、索引等数据。 段 段&#xff0c;分为数据段&#xff08;Leaf node segment)、索引段(Non-leaf node segment)、回滚段(Rollback segment)&#xff0c;InnoDB是…

GNU/Linux - Kconfig Language - 2

Kconfig syntax 配置文件描述了一系列菜单条目&#xff0c;每一行都以一个关键字开头&#xff08;帮助文本除外&#xff09;。以下关键字可结束一个菜单条目&#xff1a; The configuration file describes a series of menu entries, where every line starts with a keyword…

java 如何获取一个空的DATE对象

一&#xff1a;概述 在 Java 中&#xff0c;获取一个空的 Date 对象有多种方法。本文将介绍几种常用方法&#xff0c;并提供实际案例。 二&#xff1a;具体说明 <1>使用构造函数 Java 的 Date 类有多个构造函数&#xff0c;其中有一个无参构造函数&#xff0c;可以用于创…

ubuntu优化

rootlocalhost:~# grep -E "^(PermitRootLogin|GSSAPIAuthentication|UseDNS)" /etc/ssh/sshd_config PermitRootLogin yes GSSAPIAuthentication no UseDNS norootlocalhost:~# systemctl restart sshd#此时就可以设置root密码了rootlocalhost:~# passwd New passw…

基于深度学习的频谱分析

基于深度学习的频谱分析是一种利用深度学习算法处理和分析频谱数据的技术。频谱分析广泛应用于通信、雷达、医学成像、音频处理和地震波分析等领域。以下是关于这一领域的系统介绍&#xff1a; 1. 任务和目标 频谱分析的主要任务是从频谱数据中提取有用信息&#xff0c;具体目…

Http网络通信流程

目录 DNS域名解析 建立TCP连接 发送HTTP请求 服务器处理请求 发送HTTP响应 浏览器接收并解析响应 关闭TCP连接 DNS域名解析 步骤描述:浏览器根据用户输入的URL进行DNS域名解析,将域名转换为相应的IP地址。这是HTTP通信流程中的第一步,确保浏览器能够找到正确的Web服…