Flask实现swagger在线文档与接口测试流程详解

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}

1 2 3 4 5 6 7 8 9

@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开源地址

GitHub - flasgger/flasgger: Easy OpenAPI specs and Swagger UI for your Flask API

flasgger gitee开源地址

flasgger: Easy OpenAPI specs and Swagger UI for your Flask API

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

1 2 3 4 5 6 7 8 9 10 11 12 13

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

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:

至此完毕，基本上本案例足以应付大部分使用需求。当前根据个人习惯不同，也可以采用不同的实现方式。具体细节见开源使用说明

?现在我也找了很多测试的朋友，做了一个分享技术的交流群，共享了很多我们收集的技术文档和视频教程。
如果你不想再体验自学时找不到资源，没人解答问题，坚持几天便放弃的感受
可以加入我们一起交流。而且还有很多在自动化，性能，安全，测试开发等等方面有一定建树的技术大牛
分享他们的经验，还会分享很多直播讲座和技术沙龙
可以免费学习！划重点！开源的！！！
qq群号：485187702【暗号：csdn11】

最后感谢每一个认真阅读我文章的人，看着粉丝一路的上涨和关注，礼尚往来总是要有的，虽然不是什么很值钱的东西，如果你用得到的话可以直接拿走！?希望能帮助到你！【100%无套路免费领取】