Flask實現swagger在線文檔與接口測試流程詳解

閱讀對象:知道什麼是restful,有瞭解swagger或者openAPI更佳。

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

到此這篇關於Flask實現swagger在線文檔與接口測試流程詳解的文章就介紹到這瞭,更多相關Flask swagger內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet!

推薦閱讀: