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中，我们可以通过如下注