Django Swagger文档库drf-spectacular
在使用DRF的时候,通常的文档有:默认文档RestFrameWork、CoreAPI、Swagger,Swagger是最流行的API文档库,在绝大多数服务端开发中都有用到,之前我们使用了CoreAPI来生成文档,一方面是它不够流行,没办法和其他工具结合,另一方面可能是我不熟悉,所有有些接口并不能按照我们的要求来使用。因此我选择使用Swagger文档,之前使用过drf-yasg,但是drf-yasg现在还不支持OpenAPI 3.0,而在drf-yasg的官方文档中为我们推荐了另一个库:drf-spectacular,而且声明了drf-yasg不太可能支持OpenAPI 3.0,因此推荐我们使用drf-spectacular这个库。
安装配置
pipenv install drf-spectacular
在app中注册
# settings.py
INSTALLED_APPS = [# ALL YOUR APPS'drf_spectacular',
]
配置DRF默认schema
# settings.py
REST_FRAMEWORK = {# YOUR SETTINGS'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}
配置drf-spectacular
# settings.py
SPECTACULAR_SETTINGS = {'TITLE': '在线考试','DESCRIPTION': '在线考试系统','VERSION': '1.0.0','SERVE_INCLUDE_SCHEMA': False,# OTHER SETTINGS
}
静态资源引入
drf-spectacular 默认不包含UI资源,采用CDN方式引入网络外部资源,如果需要本地使用UI资源,可以按照一下方式引入:
pipenv install drf-spectacular[sidecar]
配置settings.py文件
INSTALLED_APPS = [# ALL YOUR APPS'drf_spectacular','drf_spectacular_sidecar', # required for Django collectstatic discovery
]
SPECTACULAR_SETTINGS = {'SWAGGER_UI_DIST': 'SIDECAR', # shorthand to use the sidecar instead'SWAGGER_UI_FAVICON_HREF': 'SIDECAR','REDOC_DIST': 'SIDECAR',# OTHER SETTINGS
}
路由配置
在根urls.py中增加路由配置
from drf_spectacular.views import SpectacularJSONAPIView, SpectacularRedocView, SpectacularSwaggerViewurlpatterns = [path('swagger/json/', SpectacularJSONAPIView.as_view(), name='schema'),# Optional UI:path('swagger/ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),path('swagger/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),# YOUR PATTERNS
]
访问:http://localhost:8000/swagger/ui/
在swagger文档中为我们生成的接口标签是根据根路由前缀自动生成的,例如以上文档的路由为:
urlpatterns = [path('', RedirectView.as_view(url='docs')),path('swagger/json/', SpectacularJSONAPIView.as_view(), name='schema'),# Optional UI:path('swagger/ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),path('swagger/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),# My Routerpath('user/', include('users.urls')),path('exam/', include('exam.urls')),path('question/', include('question.urls'))
]
如果想要修改指定接口所属的标签,我们可以使用drf-spectacular提供的extend_schema
装饰器函数,函数定义如下:
def extend_schema(operation_id: Optional[str] = None,parameters: Optional[List[Union[OpenApiParameter, _SerializerType]]] = None,request: Any = empty,responses: Any = empty,auth: Optional[List[str]] = None,description: Optional[str] = None,summary: Optional[str] = None,deprecated: Optional[bool] = None,tags: Optional[List[str]] = None,exclude: bool = False,operation: Optional[Dict] = None,methods: Optional[List[str]] = None,versions: Optional[List[str]] = None,examples: Optional[List[OpenApiExample]] = None,extensions: Optional[Dict[str, Any]] = None,
) -> Callable[[F], F]:
这个装饰器主要用于修改view在文档中的定义,参数意义如下:
- operation_id:一个唯一标识ID,基本用不到
- parameters:添加到列表中的附加或替换参数去自动发现字段。
- responses:替换
Serializer
。需要各种各样的可单独使用或组合使用的输入(有以下7种)Serializer
类- 序列化实例,比如:
Serializer(many=True)
OpenApiTypes
的基本类型或者实例OpenApiResponse
类PolymorphicProxySerializer
类- 1个字典,以状态码作为键, 以上其中一项作为值(是最常用的,格式
{200, None}
) - 1个字典,以状态码作为键,以
media_type
作为值
- request:替换序列化,接受各种输入
Serializer
类或者实例OpenApiTypes
基本类型或者实例PolymorphicProxySerializer
类- 1个字典,以
media_type
作为键,以上其中一项作为值
- auth:用auth方法的显式列表替换发现的auth
- description:替换发现的文档字符串
- summary:一个可选的短的总结描述
- deprecated:将操作标记为已弃用
- tags:覆盖默认标记列表
- exclude:设置为True以从
schema
中排除操作 - operation:手动覆盖自动发现将生成的内容。你必须提供一个兼容
OpenAPI3
的字典,该字典可以直接翻译成YAML
。 - methods:检查
extend_schema
中特殊的方法,默认匹配所有 - versions:检查
extend_schema
中特殊的API版本,默认匹配所有 - example:将请求/响应示例附加到操作中
- extensions:规范扩展
最后我们将登录、注册接口修改为Common标签
from drf_spectacular.utils import extend_schemaclass LoginView(GenericAPIView):......@extend_schema(tags=['Common'],summary='Login',description='登录接口',responses={200: str, 401: str})def post(self, request: Request):passclass RegisterView(GenericAPIView):......@extend_schema(tags=['Common'],summary='Register',description='注册接口',responses={201: UserInfoSerializer, 400: str})def post(self, request: Request):pass
注意:
使用时要注意,对于不同app下的view和Serializer要尽量使用不同的命名,否则在渲染文档的时候可能会出现异常。
自定义认证方式
在项目中我们使用了JWT作为登录认证,而drf-spectacular只对Session、Basic、Token做了适配
rest_framework.authentication.SessionAuthentication
rest_framework.authentication.BasicAuthentication
rest_framework.authentication.TokenAuthentication
这个我们在drf-spectacular/authentication.py
文件中可以看到,这个的作用就是在文档中显示什么样认证页面
对于认证页面的显示,主要是根据settings.py配置中的
REST_FRAMEWORK = {'DEFAULT_AUTHENTICATION_CLASSES': ['rest_framework.authentication.BasicAuthentication','utils.auth.authentication.JwtAuthentication'],......
}
如果drf-spectacular
可以识别 DEFAULT_AUTHENTICATION_CLASSES
下的认证方式,就会在文档登录页面上显示对应的认证方式,这里我们有自定义的认证方式,如果需要显示,要做一下适配:
from drf_spectacular.extensions import OpenApiAuthenticationExtension
from drf_spectacular.plumbing import build_bearer_security_scheme_objectclass JWTTokenScheme(OpenApiAuthenticationExtension):target_class = 'utils.auth.authentication.JwtAuthentication'name = 'JwtTokenAuth'match_subclasses = Truepriority = 1def get_security_definition(self, auto_schema):return build_bearer_security_scheme_object(header_name='Authorization',token_prefix=self.target.keyword,bearer_format='JWT')
简单解释一下,首先要继承OpenApiAuthenticationExtension
,然后target_class
中要写我们在DEFAULT_AUTHENTICATION_CLASSES
中配置的认证路径,然后重新get_security_definition
函数,返回一个字典对象,字典的键可以在OpenAPI Specification v3.0.3 | Introduction, Definitions, & More网页访问
然后再看登录认证页面
因为我们在DEFAULT_AUTHENTICATION_CLASSES
中配置了两种认证方式,因此页面就会显示两种认证方式
BUG
目前使用中存在一个BUG,就是对于read_only字段,按照我们的理解就是在查询请求是返回给客户端,而创建时在请求体中不需要包含。在默认生成的swagger界面上,我们看到的情况与理解的一样,对于JSON参数的请求是没有问题的,我们只需要输入必填的字段就可以了,但是如果是form-data参数,虽然显示的依然不包含read_only字段,请求却无法发送成功。作者也认为这是一个BUG,但是他却没有修正,
Callback schema with read-only/write-only fields · Issue #680 · tfranzel/drf-spectacular (github.com)
对于以上问题我们有两种解决方式:
- 只使用JSON格式的请求参数,缺点是必填和选填参数搞不清楚
- 在后端序列化的时候,针对不同的请求,明确的定义相对应的序列化类来处理,缺点是后端代码变多了,而且埋没了DRF为我们提供的很多使用方便的特性。
目前我采用的是第一种方式,宁愿API不明确一点,也不能增加后端的复制程度。
关注“Python运维中心”,了解更多低代码开发
Django Swagger文档库drf-spectacular相关推荐
- Django接口文档的生成
Django接口文档两种生成方法 一.django-rest_framework风格接口文档: 1.安装依赖 pip install rest_framework #如果之前有了就跳过这步 pip i ...
- 配置 Swagger 文档的自动生成
Swagger Swagger 是一个开源工具.它围绕帮助开发人员设计.构建.记录和使用 RESTful API 的 OpenAPI 规范构建.它是 RESTful Web 服务最流行的 API 文档 ...
- 基于Picture Library创建的图片文档库中的上传多个文件功能(upload multiple files)报错怎么解决?...
复现过程 首先,我创建了一个基于Picture Library的图片文档库,名字是 Pic Lib 创建完毕后,我点击它的Upload 下拉菜单,点击Upload Picture按钮 在弹出的对话框中 ...
- 创建文档库时指定文件夹(路径)
//templateList是作为模板的列表或文档库 SPList EnsureArchiveList( SPList templateList) { SPWe ...
- SharePoint 2010 文档库添加文件icon
在文档库中上传文件,它会根据上传文件的后缀名来显示个icon图标,显得很人性化.见下图(图中的pdf图标就是我添加的): 很多常用的文件格式对应的图标微软都已经提供了.但是如果我们添加的文件,微软没有 ...
- 使用SharePoint 2007 Web Service上传文件到文档库
SharePoint 2010中有了全新的客户端模型,给我们在客户端操作SharePoint对象提供了很大的方便,但是在SharePoint 2007中我们可以使用的方式就比较有限,Web Servi ...
- 使用 Swagger 文档化和定义 RESTful API
大部分 Web 应用程序都支持 RESTful API,但不同于 SOAP API--REST API 依赖于 HTTP 方法,缺少与 Web 服务描述语言(Web Services Descript ...
- Django H2 文档查看
http://python.usyiyi.cn/translate/django_182/intro/whatsnext.html 文档的组成 文档是如何更新的 最新的文档在下面 https://do ...
- SharePoint 服务器端对象模型操作文档库(上传/授权/查看权限)
来源于:http://www.cnblogs.com/jianyus/p/3258863.html 简介:上传文档到文档库,并对项目级授权,查看项目级权限方法 //在列表根目录下创建文 ...
最新文章
- http头部信息解析
- C语言 大小写字符转换
- string.Equals 比较2个字符串是否相同忽略大小写
- sharepoint权限操作(记录以备忘)
- MLPrimitive文件夹的作用
- PHP通过CURL或file_get_contents请求第三方地址
- 2009编程语言排名
- .NET Core 如何判断程序是否在远程桌面(RDP)下运行
- 详细解析Linux /etc/passwd文件
- 如何在 Web 发布规则中使用证书进行 SSL 身份验证
- 基本BASH SHELL脚本命令——切换目录以及处理文件和目录的基本知识
- 拳王虚拟项目公社:自动化的虚拟资源产品,唱歌教程赚地盆满钵满
- [WPF]根据显示区域宽度裁剪字符串
- 20190806:字符串解密
- ahoi2009维护序列
- CentOS6.7 SSH安装与配置
- linux中u盘驱动程序编写,Linux下的硬件驱动——USB设备(下)(驱动开发部分)...
- 四川途志:短视频营销公司做视频广告投放有技巧吗?
- 自我评价中专计算机600作文,中专生毕业的自我评价(精选5篇)
- 如何从godaddy转出域名
热门文章
- 2019电大计算机考试题及答案,2019年最新电大《计算机应用基础》期末考前复习综合练习题(A、B、C)及参考答案资料小抄...
- PS 反选 剪切
- 三行代码爬取京东数据
- oracle体育成绩字段,在Excel中利用自定义函数处理体育达标成绩
- Caché 命令大全
- python3 实现应用启动及关键字检测
- SaaS独角兽成长秘籍:40%法则+7步走战略
- 【深度学习】01 - 图像识别
- 路由器网口1一直闪烁正常吗_网口1一直闪烁上不了网(图文)
- vue3中使用tsx