flask-siwadoc 支持OpenAPI分組功能

openapi規(guī)范中針對(duì)接口雖然有根據(jù)標(biāo)簽分類(lèi)的功能，類(lèi)似這樣

但實(shí)際應(yīng)用場(chǎng)景中，會(huì)遇到這種情況，一份API文檔中接口數(shù)非常多，同時(shí)分為不同業(yè)務(wù)場(chǎng)景的接口，例如面向終端用戶的接口和針對(duì)管理后臺(tái)的接口。

這時(shí)候，希望有一個(gè)分組的功能來(lái)管理多個(gè)標(biāo)簽，分組下面是標(biāo)簽集合，標(biāo)簽下面再是接口集合。

這是真實(shí)場(chǎng)景中我遇到的問(wèn)題，針對(duì)這個(gè)需求我特意去查了OpenAPI規(guī)范，2017年就有人提過(guò)這個(gè)Issues，不過(guò)至今沒(méi)有得到支持。

好在，第三方UI庫(kù)提供有擴(kuò)展屬性，例如Redoc提供了一個(gè)叫x-tagGroups的屬性來(lái)滿足我們的需求。他的結(jié)構(gòu)是這樣：

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

所以，在最新版本的flask-siwadoc 我實(shí)現(xiàn)了分組的功能

我們來(lái)看看 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參數(shù)即可， 例如：auth 標(biāo)簽就會(huì)成為admin分組下面的一個(gè)標(biāo)簽。

在redoc中展示出來(lái)的效果是這樣的：

當(dāng)然，group屬性是可選的，沒(méi)有指定group時(shí)，flask-siwadoc會(huì)默認(rèn)創(chuàng)建一個(gè)值為空字符串的分組。

如果你使用swagger-ui的話，沒(méi)法體現(xiàn)出分組特性，因?yàn)槿思也恢С?。?biāo)簽名生成出來(lái)的格式是  {group}/{tag}，某種程度上的也算支持分組。

最新的flask-siwadoc 0.0.9版本已經(jīng)支持group分組特性。歡迎下載。

推薦閱讀：flask-siwadoc：一個(gè)自動(dòng)生成openapi接口文檔的庫(kù)

PS：圖靈有個(gè)618活動(dòng)，電子書(shū)全場(chǎng)5折，圖靈出版過(guò)很多好書(shū)，我在公眾號(hào)推薦過(guò)不少，感興趣的可以看看