閱讀對(duì)象：知道什么是restful，有了解swagger或者openAPI更佳。

1.什么是restful

Representional State Transfer（REST）：表征狀態(tài)轉(zhuǎn)移。是一種一種基于HTTP協(xié)議的架構(gòu)。采用Web 服務(wù)使用標(biāo)準(zhǔn)的 HTTP 方法 (GET/PUT/POST/DELETE) 將所有 Web 系統(tǒng)的服務(wù)抽象為資源。

如果REST滿(mǎn)足一定條件（C/S、無(wú)狀態(tài)、分層系統(tǒng)、統(tǒng)一接口），則稱(chēng)為REST ful。你可以理解成REST ful就是更加規(guī)范的REST。

簡(jiǎn)單總結(jié)就是我們通過(guò)http發(fā)起一個(gè)請(qǐng)求，這個(gè)請(qǐng)求可能是get請(qǐng)求，可能是post請(qǐng)求，然后從這個(gè)請(qǐng)求里面獲取到我們所需要的資源。例如A系統(tǒng)對(duì)外暴露一個(gè)接口，該接口實(shí)現(xiàn)查詢(xún)用戶(hù)信息，B系統(tǒng)通過(guò)Http請(qǐng)求到A系統(tǒng)，然后通過(guò)這個(gè)http請(qǐng)求獲取到了A系統(tǒng)的用戶(hù)資源。

換句話(huà)說(shuō)，就是我們需要實(shí)現(xiàn)restful，那么就得需要我們向外部暴露一個(gè)接口。

對(duì)于有Java開(kāi)發(fā)經(jīng)驗(yàn)的人來(lái)說(shuō)，就很簡(jiǎn)單，那就是編寫(xiě)一個(gè)Controller

例如如下Controller接口表示對(duì)外暴露一個(gè)接口，那么通過(guò)瀏覽器訪問(wèn)這個(gè)地址，我們就能獲取到這個(gè)任務(wù)信息（瀏覽器地址訪問(wèn)采用get請(qǐng)求方式）

<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能做什么

在沒(méi)有swagger之前，我們可以使用word，excel等功能來(lái)書(shū)寫(xiě)接口定義文檔，但又有一個(gè)弊端。

即： 在接口改變時(shí)需要及時(shí)的同步接口文檔，否則實(shí)際的接口與接口文檔不相符，則接口文件就失去了作用，甚至?xí)鸬椒醋饔谩?/p>

比如上述接口一開(kāi)始采用的是get請(qǐng)求，并且taskId是通過(guò)地址傳參，假設(shè)現(xiàn)在維護(hù)代碼的人將請(qǐng)求改成post，然后taskId放到請(qǐng)求body中，例如變成post+json的方式，但是很可能忘記維護(hù)接口文檔，導(dǎo)致接口文檔和實(shí)際接口不一致。

在Java中，我們可以根據(jù)在代碼中使用自定義的注解來(lái)生成接口文檔，這個(gè)在前后端分離的項(xiàng)目中很重要。這樣做的好處是 在開(kāi)發(fā)接口時(shí)可以通過(guò)swagger 將接口文檔定義好，同時(shí)也方便以后的維護(hù)。

例如在Java中，我們可以通過(guò)如下注解：@API、@ApiModelProperty等注解來(lái)修飾我們代碼。

在python中，類(lèi)似的功能叫做裝飾器

此時(shí)訪問(wèn)swagger，我們即可看到如下在線(xiàn)的一個(gè)文檔，這個(gè)文檔能將我們Java代碼里面的注解描述信息是保持一致的。

當(dāng)然，Java畢竟生態(tài)很成熟，上述的原生swagger不太符合我們目前的使用習(xí)慣，因此使用如下的顯示插件

OpenAPI3 (swagger3) 訪問(wèn)地址：http://127.0.0.1:9090/swagger-ui/index.html

knife4j UI 訪問(wèn)地址：http://127.0.0.1:9090/doc.html

我們可以點(diǎn)擊調(diào)試，即可在線(xiàn)測(cè)試這個(gè)接口的功能，等價(jià)于把postman這種接口測(cè)試工具集成進(jìn)來(lái)了。

3.python如何實(shí)現(xiàn)swagger

在flask框架中使用的swagger即為flasgger，flasgger是flask支持的swagger UI，便于調(diào)試使用flask框架搭建的web api接口

flasgger安裝

pip install flasgger

flasgger github開(kāi)源地址

https://github.com/flasgger/flasgger

flasgger gitee開(kāi)源地址

https://gitee.com/Flasgger/flasgger

4.flasgger的使用案例

比如我們現(xiàn)在需要對(duì)外提供一個(gè)接口，這個(gè)接口的請(qǐng)求參數(shù)如下，參數(shù)格式是一個(gè)復(fù)雜的JSON格式，包含了字符串（userName）,對(duì)象（userInfo）,數(shù)字（age），數(shù)組（hobby），基本上這個(gè)請(qǐng)求參數(shù)覆蓋我們百分之99的參數(shù)需求了

訪問(wèn)地址

http://127.0.0.1:8085/apidocs/

當(dāng)我們集成完畢后，打開(kāi)如上地址，就能打開(kāi)python版本的swagger的頁(yè)面

可以查看Models，這個(gè)models是描述各個(gè)參數(shù)，點(diǎn)擊這個(gè)方法，就可以看到調(diào)用的示例，可以點(diǎn)擊界面的try it out，就可以進(jìn)行請(qǐng)求調(diào)試了

進(jìn)入調(diào)試頁(yè)面，修改參數(shù)后，點(diǎn)擊執(zhí)行(Execute)按鈕。

如下就是此次我們調(diào)用接口返回的信息了。

對(duì)比之前的Java版本，我們發(fā)現(xiàn)，畫(huà)面基本保持一致。當(dāng)然了由于Java生態(tài)好，所以還有bootstrapUI或者knife4j UI（換一種UI的風(fēng)格展示swagger）的支持，暫時(shí)在python中沒(méi)找到bootstrap和knife4j對(duì)python版本的swagger的支持。

如果您有python版本的bootstrapUI或者knife4j UI，或者有類(lèi)似的UI，還請(qǐng)聯(lián)系我，大家一起學(xué)習(xí)，學(xué)習(xí)。

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進(jìn)行在線(xiàn)文檔生成，添加用戶(hù)信息，請(qǐng)求參數(shù)覆蓋了常用的字符串、對(duì)象、數(shù)組、數(shù)字
parameters:
  - name: body
    in: body
    required: true
    schema:
      id: 接口參數(shù)示例
      properties:
        userName:
          type: string
          description: 用戶(hù)自己的姓名
        userInfo:
            properties:
              hobby:
                type: array
                items:
                  type: string
                description: 用戶(hù)的愛(ài)好
              age:
                type: integer
                description: 用戶(hù)年齡
responses:
  200:
     description: 添加用戶(hù)成功
     example:
  500:
     description: 添加用戶(hù)失敗
     example:

至此完畢，基本上本案例足以應(yīng)付大部分使用需求。當(dāng)前根據(jù)個(gè)人習(xí)慣不同，也可以采用不同的實(shí)現(xiàn)方式。具體細(xì)節(jié)見(jiàn)開(kāi)源使用說(shuō)明

flasgger github開(kāi)源地址

https://github.com/flasgger/flasgger

flasgger gitee開(kāi)源地址

https://gitee.com/Flasgger/flasgger

到此這篇關(guān)于Flask實(shí)現(xiàn)swagger在線(xiàn)文檔與接口測(cè)試流程詳解的文章就介紹到這了,更多相關(guān)Flask swagger內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論