Flasgger使用心得

发表于 | 分类于 |

引言

  • Flask是一款流行的Python实现的Web开发微框架；
  • Swagger是一款Restful接口的文档在线自动生成+功能测试功能软件；
  • 通过swagger能够清晰、便捷地调试符合Restful规范的API；
  • 在flask框架中使用的swagger即为flasgger，flasgger是flask支持的swagger UI，便于调试使用flask框架搭建的web api接口；
  • 本文介绍了flasgger的用法和不足之处。

使用方法

  • 首先，需要在项目中安装flasgger，具体方法有两种：
    • 方法一：在visual studio中右键工程，搜索flasgger，自动安装；
    • 方法二：使用pip命令，pip install flasgger；
  • 安装后，使用下面的程序框架，搭建最简单的web api：
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
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)
  • 从上面的程序我们可以看出，只要将yaml格式的flasgger描述性程序放置在两组双引号之间的位置，即可实现flasgger的基本功能；
  • 访问http://localhost:5000/apidocs/index.html 即可看到flasgger页面；

flasgger

  • 当然，上面的yaml描述性程序可以放置在单独的文件中，那么api中用@符号引入这个文件即可：
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
import random
from flask import Flask, jsonify, request
from flasgger import Swagger
from flasgger.utils import swag_from

app = Flask(__name__)
Swagger(app)

@app.route('/api/<string:language>/', methods=['GET'])
@swag_from('index.yml')
def index(language):
    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)

flasgger配置文件解析：

  • 在flasgger的配置文件中，以yaml的格式描述了flasgger页面的内容；
  • tags标签中可以放置对这个api的描述和说明；
  • parameters标签中可以放置这个api所需的参数，如果是GET方法，可以放置url中附带的请求参数，如果是POST方法，可以将参数放置在schema子标签下面；
  • responses标签中可以放置返回的信息，以状态码的形式分别列出，每个状态码下可以用schema标签放置返回实体的格式；

flasgger的不足

  • flasgger的配置文件中，对于POST方法，在描述POST body的schema标签中，不支持以yaml格式描述的数组或嵌套的object，这使得页面上面无法显示这类POST body的example；
  • 解决方案：将这类POST body的example放置在description部分（三横杠”—“上面的部分），由于description部分是用html格式解析的，所以可以以html的语法编写；

参考

您的支持是对我最大的鼓励！