Swagger 和 Python 配合使用

1 简介

先来看一个应用场景：

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

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

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

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

2 Python & Flask & Swagger 实现

2.1 工具介绍

Python

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

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

Flask

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

Swagger

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

Nodejs 与 npm

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

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

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

2.2 安装 Node 工具集

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

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

2.3 安装 Python 的三方工具包

1
2
$ sudo pip install flask
$ sudo pip install flasgger

2.4 方法一：Python 程序中实现

编写 test.py 程序

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
#coding:utf8

import sys
import random
reload(sys)
sys.setdefaultencoding('utf8')
from flask import Flask,Blueprint,render_template,request,redirect,jsonify
from flasgger import Swagger,swag_from

app = Flask(__name__)
Swagger(app)

@app.route('/api/<string:language>/', methods=['GET'])
def index(language):
    """
    This is the language awesomeness API
    Call this api passing a language name and get back its features
    ---
    tags:
      - Awesomeness Language API
    parameters:
      - name: language
        in: path
        type: string
        required: true
        description: The language name
      - name: size
        in: query
        type: integer
        description: size of awesomeness
    responses:
      500:
        description: Error The language is not awesome!
      200:
        description: A language with its awesomeness
        schema:
          id: awesome
          properties:
            language:
              type: string
              description: The language name
              default: Lua
            features:
              type: array
              description: The awesomeness list
              items:
                type: string
              default: ["perfect", "simple", "lovely"]

    """

    language = language.lower().strip()
    features = [
        "awesome", "great", "dynamic", 
        "simple", "powerful", "amazing", 
        "perfect", "beauty", "lovely"
    ]
    size = int(request.args.get('size', 1))
    if language in ['php', 'vb', 'visualbasic', 'actionscript']:
        return "An error occurred, invalid language for awesomeness", 500
    return jsonify(
        language=language,
        features=random.sample(features, size)
    )

app.run(debug=True)

2.4.1 运行 test.py 程序

1
$ python test.py

此时，用浏览器访问：http://localhost:5000/apidocs/，就可以看到 Swagger 界面了，程序中双引号内是一个非常简单的接口描述。

方法二：写在 yml 程序中

用@swag_from('index.yml') 的方式，将描述文件 yml 引入程序。

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

python 程序

1
2
3
4
5
6
@app.route('/parse', methods=['POST'])
@swag_from('yml/parse_html.yml')
def parse(with_dse = False, debug=False):
    info = request.values
    use_openai = info.get('use_openai')
    ....

yml 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
tags:
  - 文档解析接口
description:
  - 解析文档, 以 json 串格式返回
schemes:
  - http
parameters:
  - name: file
    in: formData
    type: string
    ....
```    

## 3 其它工具和方法

&emsp; 在网上看到一般安装 swagger 方法，是从 git 下载 swagger-edit，swagger-ui：

$ git clone https://github.com/swagger-api/swagger-editor $ git clone https://github.com/swagger-api/swagger-ui ```

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

4 参考

Flasgger 使用心得

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