flask-siwadoc 支持openapi 分组功能

By 刘志军, 2022-06-10, 分类: Python

flask-siwadoc, python

openapi规范中针对接口虽然有根据标签分类的功能,类似这样

但实际应用场景中,会遇到这种情况,一份API文档中接口数非常多,同时分为不同业务场景的接口,例如面向终端用户的接口和针对管理后台的接口。

这时候,希望有一个分组的功能来管理多个标签,分组下面是标签集合,标签下面再是接口集合。

这是真实场景中我遇到的问题,针对这个需求我特意去查了OpenAPI规范,2017年就有人提过这个Issues,不过至今没有得到支持。

好在,第三方UI库提供有扩展属性,例如Redoc提供了一个叫x-tagGroups的属性来满足我们的需求。他的结构是这样:

{
  "x-tagGroups": [
    {
      "name": "Customers",
      "tags": ["Customers", "Customer Authentication", "AML", "Customers Timeline"]
    },
    {
      "name": "Payment Instruments",
      "tags": ["Payment Instruments", "Payment Tokens", "Payment Cards"]
    }
  ]
}

所以,在最新版本的flask-siwadoc 我实现了分组的功能

我们来看看 flask-siwadoc 如何使用分组

@app.route("/admin/login", methods=["POST"])
@siwa.doc(body=LoginModel, resp=UserModel, tags=['auth'], group='admin')
def admin_login(body: LoginModel):
    return {"username": body.username, "id": 1}

只需要在doc装饰器中指定group参数即可, 例如:auth 标签就会成为admin分组下面的一个标签。

在redoc中展示出来的效果是这样的:

当然,group属性是可选的,没有指定group时,flask-siwadoc会默认创建一个值为空字符串的分组。

如果你使用swagger-ui的话,没法体现出分组特性,因为人家不支持。标签名生成出来的格式是 {group}/{tag},某种程度上的也算支持分组。

最新的flask-siwadoc 0.0.9版本已经支持group分组特性。欢迎下载。


有问题可以扫描二维码和我交流

关注公众号「Python之禅」,回复「1024」免费获取Python资源

python之禅

猜你喜欢

2015-12-24
Python字典对象实现原理
2017-12-26
5个酷毙的Python工具
2018-10-15
提升逼格的两个函数:setdefault 与 defaultdict
2014-02-10
python 函数式编程处理函数:map(),filter(),reduce()
2017-09-01
关于操作 Python 列表最常见的10个问答
2020-06-07
求求你,别再手工造假数据了,fake了解一下
2019-05-12
Python 字符串转日期时间
2020-06-02
用python创建csv表格文件
2016-09-18
分析urllib.unquote乱码的原因
2017-06-29
for循环在Python中是怎么工作的