flask-siwadoc 支持OpenAPI分组功能
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分组特性。欢迎下载。
推荐阅读：flask-siwadoc：一个自动生成openapi接口文档的库
PS：图灵有个618活动，电子书全场5折，图灵出版过很多好书，我在公众号推荐过不少，感兴趣的可以看看
评论