Swagger和Python配合自动生成接口文档

说明

 先来看一个应用场景:

 我写了一段功能性的程序(可能是Java的,也可能是Python的),供他人调用(调我程序可能是其它编程语言,或者直接运行,如果调用者对我使用的工具不熟悉,直接调用可能很麻烦),这个程序需要传入多个参数,需要结构化的输出,我以什么方式提供给比较好呢?

 我们可能会选择BS的结构,建立一个Web-Server,然后把功能性的程序放在Web-Server上并向外暴露接口,其它程序用Http协议调用该接口,以POST或GET的方式转入参数,然后得到返回结果。

 于是我们就需要定义一些交互协议,写接口描述文档,在调用出错时,联调是哪一端的问题,总之,沟通成本很高。

 Swagger可以很好地解这一问题,一方面,它能按规范自动生成接口文档(以网页形式提供),这样编写API和编写文档同时完成,几乎不用考虑文本和代码版本不同步的问题;另一方面,它能提供测试界面,我们只需要在网页上填写相应的参数,点击调用(网页由swagger生成),就可以轻松调用接口,使得服务端的开发者,不使用客户端,就可以完整地调试代码。

Python & Flask & Swagger实现

(1) 工具介绍

i. Python

 在这里选择介绍Python+Swagger,因为Python真的非常简单,不需要关心太多的代码,库,复杂的环境,只要关注流程本身即可。

 另外,我这里的开发环境是python 2.7。

ii. Flask

 Flask是Python的Web框架,Python的Web框架还有Django,Tornado,Bottle等等,Flask功能虽然不及Django和Tornado强大,但它是个轻量级的工具,三方开源组件也比较丰富。

iii. Swagger

 支持Python+Flask的Swagger库不少,有flask-swag,flask-swagger,flasgger,本例中选用的是flasgger,它的软件包中包括了Swagger-UI,除了安装工具包,几乎不需要配置其它环境。

iv. Nodejs与npm

 Nodejs是服务器后端的JavaScript的工具。

 Npm是一个JavaScript的包管理程序,它就像python中的pip,用于下载和管理三方工具。

 Swagger主要是用javascript实现的,因此依赖node工具集。

(2) 安装Node工具集

 虽然node能用apt-get方式安装,但最好下载使用最新版本的node,版本太旧可能遇到各种问题。

 我下载的是http://nodejs.cn/download/ 中64位的linux版本,这里面也包括NPM工具,不用另外安装。解压之后,将其中的bin, lib等目录复制到/usr/local/的对应目录下即可使用。

(3) 安装Python的三方工具包

(4) 编写test.py程序

(5) 运行test.py程序

 此时,用浏览器访问:http://localhost:5000/apidocs/,就可以看到Swagger界面了,程序中双引号内是一个非常简单的接口描述,我们可以把它写程序中,或者用@swag_from('index.yml')的方式,将描述文件yml引入程序。

在该界面上点“try it out”,按钮就可以在网页上测试该接口。

其它工具和方法

 在网上看到一般安装swagger方法,是从git下载swagger-edit,swagger-ui:

 然后用工具http-server通过调用其目录中的index.html提供Web界面,其中的接口在yml文件中定义,yml接口一般是在编写API时程序时,通过引入swagger相关库,按照规则,自动生成的,手动编写yml文件的比较少。步骤也相对比较复杂。

参考

(1) Flasgger使用心得

https://changsiyuan.github.io/2017/05/20/2017-5-20-flasgger/

搜索添加公众号:算法学习分享

  • 发表于:
  • 原文链接https://kuaibao.qq.com/s/20180812G0Z79000?refer=cp_1026
  • 腾讯「云+社区」是腾讯内容开放平台帐号(企鹅号)传播渠道之一,根据《腾讯内容开放平台服务协议》转载发布内容。
  • 如有侵权,请联系 yunjia_community@tencent.com 删除。

扫码关注云+社区

领取腾讯云代金券