阅读对象：知道什么是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://www.toymoban.com/news/detail-660132.html
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
文章来源地址https://www.toymoban.com/news/detail-660132.html
到了这里，关于python基于flask实现swagger在线文档以及接口测试的文章就介绍完了。如果您还想了解更多内容，请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
