flask-siwadoc 支援openapi 分組功能

語言: CN / TW / HK

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資源