flask 配置swagger服務(wù)

Flask 配置并使用 Swagger 服務(wù).

flask-swagger 是什么

在使用之前栅组,我們先來了解下 flask-swagger 是什么瑟俭,如下內(nèi)容障斋,來自官網(wǎng)。

flask-swagger 提供 swagger方法泪掀,可以掃描 flask 中包含 yaml 格式的文檔注釋听绳,文檔注釋格式與 Swagger 2.0 Operation 對象一致。

例如:

class UserAPI(MethodView):

    def post(self):
        """
        Create a new user
        ---
        tags:
          - users
        definitions:
          - schema:
              id: Group
              properties:
                name:
                 type: string
                 description: the group's name
        parameters:
          - in: body
            name: body
            schema:
              id: User
              required:
                - email
                - name
              properties:
                email:
                  type: string
                  description: email for user
                name:
                  type: string
                  description: name for user
                address:
                  description: address for user
                  schema:
                    id: Address
                    properties:
                      street:
                        type: string
                      state:
                        type: string
                      country:
                        type: string
                      postalcode:
                        type: string
                groups:
                  type: array
                  description: list of groups
                  items:
                    $ref: "#/definitions/Group"
        responses:
          201:
            description: User created
        """
        return {}

flask-swagger 支持 MethodView 方法級別的文檔注釋和普通 flask view 方法异赫。

底層實現(xiàn):應(yīng)用掃描文檔椅挣,把文檔注釋中---前,第一張內(nèi)容作為 summary 字段塔拳,其余行作為description字段鼠证,---之后的文檔注釋,作為 Swagger Operation 對象處理靠抑。

支持在注釋中添加 ParameterResponse 支持內(nèi)聯(lián)的 Schema對象量九,

另外,docstring 也可以放到額外的文件中颂碧。
eg.

Create a new user
---
tags:
  - users
definitions:
  - schema:
      id: Group
      properties:
        name:
         type: string
         description: the group's name
parameters:
  - in: body
    name: body
    schema:
      id: User
      required:
        - email
        - name
      properties:
        email:
          type: string
          description: email for user
        name:
          type: string
          description: name for user
        address:
          description: address for user
          schema:
            id: Address
            properties:
              street:
                type: string
              state:
                type: string
              country:
                type: string
              postalcode:
                type: string
        groups:
          type: array
          description: list of groups
          items:
            $ref: "#/definitions/Group"
responses:
  201:
    description: User created

使用時荠列,在文檔注釋中添加:

class UserAPI(MethodView):

    def post(self):
        """
        Create a new user

        blah blah

        swagger_from_file: path/to/file.yml

        blah blah
        """
        return {}

swagger_from_file 可以替換.

安裝使用

了解基礎(chǔ)之后,開始安裝并配置使用稚伍,先安裝這個庫弯予。

pip install flask-swagger

另外戚宦,需要在 flask 中配置 spec

@app.route("/spec")
def spec():
    swag = swagger(app)
    swag['info']['version'] = "1.0"
    swag['info']['title'] = "My API"
    return jsonify(swag)

現(xiàn)在配置可以生成 json 格式的 OpenAPI 內(nèi)容了个曙。只有 json 有什么用,我們需要Web頁面的Swagger可以訪問。另外還需要將 json 放到 swagger-ui 中. swagger-ui 的地址如下: https://github.com/swagger-api/swagger-ui垦搬。

swagger-ui 項目包含靜態(tài)的頁面呼寸,為了方便,我們將靜態(tài)頁面猴贰,放到 flask 項目的靜態(tài)頁面中对雪,如下圖所示。

img

修改 swagger index.html中默認(rèn)的URL https://petstore.swagger.io/v2/swagger.json 改成通過 flask 傳入的地址 {{ url }}米绕,這樣做的目的是瑟捣,我們可以在配置或者業(yè)務(wù)中,動態(tài)修改URL, 如下栅干。

    window.onload = function() {
      
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        // url: "https://petstore.swagger.io/v2/swagger.json",
        url: "{{ url }}",
        "dom_id": "#swagger-ui",
        ...
      })

URL通常包括請求協(xié)議迈套,請求地址和端口,這里碱鳞,我們將這些參數(shù)寫到配置文件中桑李,這樣傳遞:

@app.route('/swagger')
def swagger_index():
    return render_template("swagger/index.html", **{
        "url": "http://" + config.IP_ADDRESS + ":" + str(config.PORT) + "/spec"
    })

最終的效果如下所示

img

)

完整的代碼示例,可通過 https://github.com/RiverLiu/demos/tree/master/python/flask-swagger-example 下載.

附錄

OpenAPI Specification 2.0

OpenApi 3.0.3

Notes

swagger-ui 存在版本兼容的問題窿给,swagger 有 2.0 和 3.0 版本贵白,flask-swagger 3.18.3 版支持 swagger 2.0 和 3.0

最后編輯于
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
  • 序言:七十年代末,一起剝皮案震驚了整個濱河市崩泡,隨后出現(xiàn)的幾起案子禁荒,更是在濱河造成了極大的恐慌,老刑警劉巖允华,帶你破解...
    沈念sama閱讀 219,539評論 6 508
  • 序言:濱河連續(xù)發(fā)生了三起死亡事件圈浇,死亡現(xiàn)場離奇詭異,居然都是意外死亡靴寂,警方通過查閱死者的電腦和手機磷蜀,發(fā)現(xiàn)死者居然都...
    沈念sama閱讀 93,594評論 3 396
  • 文/潘曉璐 我一進店門,熙熙樓的掌柜王于貴愁眉苦臉地迎上來百炬,“玉大人褐隆,你說我怎么就攤上這事∑视唬” “怎么了庶弃?”我有些...
    開封第一講書人閱讀 165,871評論 0 356
  • 文/不壞的土叔 我叫張陵,是天一觀的道長德澈。 經(jīng)常有香客問我歇攻,道長,這世上最難降的妖魔是什么梆造? 我笑而不...
    開封第一講書人閱讀 58,963評論 1 295
  • 正文 為了忘掉前任缴守,我火速辦了婚禮,結(jié)果婚禮上,老公的妹妹穿的比我還像新娘屡穗。我一直安慰自己贴捡,他們只是感情好,可當(dāng)我...
    茶點故事閱讀 67,984評論 6 393
  • 文/花漫 我一把揭開白布村砂。 她就那樣靜靜地躺著烂斋,像睡著了一般。 火紅的嫁衣襯著肌膚如雪础废。 梳的紋絲不亂的頭發(fā)上汛骂,一...
    開封第一講書人閱讀 51,763評論 1 307
  • 那天,我揣著相機與錄音评腺,去河邊找鬼香缺。 笑死,一個胖子當(dāng)著我的面吹牛歇僧,可吹牛的內(nèi)容都是我干的图张。 我是一名探鬼主播,決...
    沈念sama閱讀 40,468評論 3 420
  • 文/蒼蘭香墨 我猛地睜開眼诈悍,長吁一口氣:“原來是場噩夢啊……” “哼祸轮!你這毒婦竟也來了?” 一聲冷哼從身側(cè)響起侥钳,我...
    開封第一講書人閱讀 39,357評論 0 276
  • 序言:老撾萬榮一對情侶失蹤适袜,失蹤者是張志新(化名)和其女友劉穎,沒想到半個月后舷夺,有當(dāng)?shù)厝嗽跇淞掷锇l(fā)現(xiàn)了一具尸體苦酱,經(jīng)...
    沈念sama閱讀 45,850評論 1 317
  • 正文 獨居荒郊野嶺守林人離奇死亡,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內(nèi)容為張勛視角 年9月15日...
    茶點故事閱讀 38,002評論 3 338
  • 正文 我和宋清朗相戀三年给猾,在試婚紗的時候發(fā)現(xiàn)自己被綠了疫萤。 大學(xué)時的朋友給我發(fā)了我未婚夫和他白月光在一起吃飯的照片。...
    茶點故事閱讀 40,144評論 1 351
  • 序言:一個原本活蹦亂跳的男人離奇死亡敢伸,死狀恐怖扯饶,靈堂內(nèi)的尸體忽然破棺而出,到底是詐尸還是另有隱情池颈,我是刑警寧澤尾序,帶...
    沈念sama閱讀 35,823評論 5 346
  • 正文 年R本政府宣布,位于F島的核電站躯砰,受9級特大地震影響每币,放射性物質(zhì)發(fā)生泄漏。R本人自食惡果不足惜琢歇,卻給世界環(huán)境...
    茶點故事閱讀 41,483評論 3 331
  • 文/蒙蒙 一兰怠、第九天 我趴在偏房一處隱蔽的房頂上張望则北。 院中可真熱鬧,春花似錦痕慢、人聲如沸。這莊子的主人今日做“春日...
    開封第一講書人閱讀 32,026評論 0 22
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽。三九已至娜庇,卻和暖如春塔次,著一層夾襖步出監(jiān)牢的瞬間,已是汗流浹背名秀。 一陣腳步聲響...
    開封第一講書人閱讀 33,150評論 1 272
  • 我被黑心中介騙來泰國打工励负, 沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留,地道東北人匕得。 一個月前我還...
    沈念sama閱讀 48,415評論 3 373
  • 正文 我出身青樓继榆,卻偏偏與公主長得像,于是被迫代替她去往敵國和親汁掠。 傳聞我的和親對象是個殘疾皇子略吨,可洞房花燭夜當(dāng)晚...
    茶點故事閱讀 45,092評論 2 355

推薦閱讀更多精彩內(nèi)容