Flask實現swagger線上檔案與介面測試流程詳解

2022-07-30 18:02:35

1.什麼是restful

Representional State Transfer（REST）：表徵狀態轉移。是一種一種基於HTTP協定的架構。採用Web 服務使用標準的 HTTP 方法 (GET/PUT/POST/DELETE) 將所有 Web 系統的服務抽象為資源。

如果REST滿足一定條件（C/S、無狀態、分層系統、統一介面），則稱為REST ful。你可以理解成REST ful就是更加規範的REST。

簡單總結就是我們通過http發起一個請求，這個請求可能是get請求，可能是post請求，然後從這個請求裡面獲取到我們所需要的資源。例如A系統對外暴露一個介面，該介面實現查詢使用者資訊，B系統通過Http請求到A系統，然後通過這個http請求獲取到了A系統的使用者資源。

換句話說，就是我們需要實現restful，那麼就得需要我們向外部暴露一個介面。

對於有Java開發經驗的人來說，就很簡單，那就是編寫一個Controller

例如如下Controller介面表示對外暴露一個介面，那麼通過瀏覽器存取這個地址，我們就能獲取到這個任務資訊（瀏覽器地址存取採用get請求方式）

<IP:埠/域名>/task/info/{taskId}

@RestController
@RequestMapping("/task")
public class TaskController {
	@GetMapping("/info/{taskId}")
	public R<TaskRes> getmTaskInfoById(@PathVariable String taskId) {
		TaskRes task = taskService.getTaskInfoById(taskId);
		return R.ok(task);
	}
}

2.swagger/openAPI能做什麼

在沒有swagger之前，我們可以使用word，excel等功能來書寫介面定義檔案，但又有一個弊端。

即：在介面改變時需要及時的同步介面檔案，否則實際的介面與介面檔案不相符，則介面檔案就失去了作用，甚至會起到反作用。

比如上述介面一開始採用的是get請求，並且taskId是通過地址傳參，假設現在維護程式碼的人將請求改成post，然後taskId放到請求body中，例如變成post+json的方式，但是很可能忘記維護介面檔案，導致介面檔案和實際介面不一致。

在Java中，我們可以根據在程式碼中使用自定義的註解來生成介面檔案，這個在前後端分離的專案中很重要。這樣做的好處是在開發介面時可以通過swagger 將介面檔案定義好，同時也方便以後的維護。

例如在Java中，我們可以通過如下註解：@API、@ApiModelProperty等註解來修飾我們程式碼。

在python中，類似的功能叫做裝飾器

此時存取swagger，我們即可看到如下線上的一個檔案，這個檔案能將我們Java程式碼裡面的註解描述資訊是保持一致的。

當然，Java畢竟生態很成熟，上述的原生swagger不太符合我們目前的使用習慣，因此使用如下的顯示外掛

OpenAPI3 (swagger3) 存取地址：http://127.0.0.1:9090/swagger-ui/index.html

knife4j UI 存取地址：http://127.0.0.1:9090/doc.html

我們可以點選偵錯，即可線上測試這個介面的功能，等價於把postman這種介面測試工具整合進來了。

3.python如何實現swagger

在flask框架中使用的swagger即為flasgger，flasgger是flask支援的swagger UI，便於偵錯使用flask框架搭建的web api介面

flasgger安裝

pip install flasgger

flasgger github開源地址

https://github.com/flasgger/flasgger

flasgger gitee開源地址

https://gitee.com/Flasgger/flasgger

4.flasgger的使用案例

比如我們現在需要對外提供一個介面，這個介面的請求引數如下，引數格式是一個複雜的JSON格式，包含了字串（userName）,物件（userInfo）,數位（age），陣列（hobby），基本上這個請求引數覆蓋我們百分之99的引數需求了

存取地址

http://127.0.0.1:8085/apidocs/

當我們整合完畢後，開啟如上地址，就能開啟python版本的swagger的頁面

可以檢視Models，這個models是描述各個引數，點選這個方法，就可以看到呼叫的範例，可以點選介面的try it out，就可以進行請求偵錯了

進入偵錯頁面，修改引數後，點選執行(Execute)按鈕。

如下就是此次我們呼叫介面返回的資訊了。

對比之前的Java版本，我們發現，畫面基本保持一致。當然了由於Java生態好，所以還有bootstrapUI或者knife4j UI（換一種UI的風格展示swagger）的支援，暫時在python中沒找到bootstrap和knife4j對python版本的swagger的支援。

如果您有python版本的bootstrapUI或者knife4j UI，或者有類似的UI，還請聯絡我，大家一起學習，學習。

5.完整程式碼

app.py

from flask import Flask, jsonify, request
from flasgger import Swagger, swag_from
server = Flask(__name__)
Swagger(server)
server.config['JSON_AS_ASCII']=False
@server.route('/flask/flasgger/demo',methods=['POST'])
@swag_from('demo.yml')
def demo_request():
    json_data = request.json
    result = {"code":"200","msg":"SUCCES","data":{"name":"xxxxxx","age":25,"job":"python"}}
    return jsonify(result)
if __name__ == "__main__":
    server.run(port=8085,debug=True)

demo.yml

tags:
  - falsk整合swagger範例
description:
    範例flasgger進行線上檔案生成，新增使用者資訊，請求引數覆蓋了常用的字串、物件、陣列、數位
parameters:
  - name: body
    in: body
    required: true
    schema:
      id: 介面引數範例
      properties:
        userName:
          type: string
          description: 使用者自己的姓名
        userInfo:
            properties:
              hobby:
                type: array
                items:
                  type: string
                description: 使用者的愛好
              age:
                type: integer
                description: 使用者年齡
responses:
  200:
     description: 新增使用者成功
     example:
  500:
     description: 新增使用者失敗
     example:

至此完畢，基本上本案例足以應付大部分使用需求。當前根據個人習慣不同，也可以採用不同的實現方式。具體細節見開源使用說明

flasgger github開源地址

https://github.com/flasgger/flasgger

flasgger gitee開源地址

https://gitee.com/Flasgger/flasgger