接手了一个用Flask写的API项目，但一看到项目里那散落着的残缺的Markdown文档，你就觉得头大。

能不能生成一个可以清晰描述接口，还能进行交互测试的文档呢？

Swagger，这个用于生成、描述、调用和可视化 RESTful 风格的 Web 服务框架，已经成为 API 文档的事实标准。

而 Flasgger，把 Swagger 带给了 Flask。

简介

Flasgger，是 flasgger 组织在Github上开源的解析和渲染 SwaggerUI 的 Flask 拓展。

其提供了对于Swagger文档标准的解析和SwaggerUI的生成，支持使用YAML、Python字典和Marshmallow Schema的定义，

支持使用JSON Schema进行数据验证，支持Flask-RESTful框架的使用，对于使用Flask框架的开发者而言十分方便。

安装

使用 pip 安装即可：

pip install flasgger

如果需要使用 Marshmallow Schema，那么还需要依赖

pip install marshmallow apispec

示例

Flasgger支持直接在docstring中进行文档YAML格式的定义：

from flask import Flask, jsonify
from flasgger import Swagger

app = Flask(__name__)
swagger = Swagger(app)

@app.route('/colors/<palette>/')
def colors(palette):
    """Example endpoint returning a list of colors by palette
    This is using docstrings for specifications.
    ---
    parameters:
      - name: palette
        in: path
        type: string
        enum: ['all', 'rgb', 'cmyk']
        required: true
        default: all
    definitions:
      Palette:
        type: object
        properties:
          palette_name:
            type: array
            items:
              $ref: '#/definitions/Color'
      Color:
        type: string
    responses:
      200:
        description: A list of colors (may be filtered by palette)
        schema:
          $ref: '#/definitions/Palette'
        examples:
          rgb: ['red', 'green', 'blue']
    """
    all_colors = {
        'cmyk': ['cian', 'magenta', 'yellow', 'black'],
        'rgb': ['red', 'green', 'blue']
    }
    if palette == 'all':
        result = all_colors
    else:
        result = {palette: all_colors.get(palette)}

    return jsonify(result)

app.run(debug=True)

这是一个完整的Flask 应用例子，我们定义了一个接口，它接受色调参数，返回颜色的列表。

可以看到，可以直接把Swagger的文档定义直接放在接口的docstring中，进行了包括参数、数据结构定义、示例响应等的定义。

运行应用，Flassger就会对文档定义进行解析，并生成SwaggerUI的文档界面。

运行后，访问 http://localhost:5000/apidocs/，就会看到生成的文档界面。

可以看到，这是Swagger提供的文档界面，上面包含了我们刚刚定义的接口的定义。

此外，展开参数栏，我们可以看到接口的参数palette的类型和可选值等描述，

并且可以进行接口的测试，调用接口，并显示返回的HTTP响应。

文档中还展示了我们定义的数据类型。

此外，我们还可以把文档写在独立的YAML文件中，再在接口中引用。可以使用装饰器来引用：

from flasgger import swag_from

@app.route('/colors/<palette>/')
@swag_from('colors.yml')
def colors(palette):
    ...

也可以在docstring中使用file来标注：
@app.route('/colors/<palette>/')
def colors(palette):
    """
    file: colors.yml
    """
    ...

也可以在docstring中使用file来标注：

@app.route('/colors/<palette>/')
def colors(palette):
    """
    file: colors.yml
    """
    ...

我们也可以结合Python序列化库 Marshmallow 来进行文档的定义

class Color(Schema):
    name = fields.Str()

class Palette(Schema):
    pallete_name = fields.Str()
    colors = fields.Nested(Color, many=True)

class PaletteView(SwaggerView):
    parameters = [
        {
            "name": "palette",
            "in": "path",
            "type": "string",
            "enum": ["all", "rgb", "cmyk"],
            "required": True,
            "default": "all"
        }
    ]
    responses = {
        200: {
            "description": "A list of colors (may be filtered by palette)",
            "schema": Palette
        }
    }

我们可以看到，相比于前面使用JSON Schema的方式，这里直接引用了Marshmallow的Schema来进行数据类型的定义

此外，还可以利用Json Schema对定义的接口进行输入数据的验证等，当验证不通过就会抛出异常并返回错误信息。

@swag_from('defs.yml', validation=True)
def post():
    ...

总结

Flassger把Swagger引入到了Flask中，使得在Flask的API开发能够快速地进行文档的编写和展示，方便了项目的对接和后期维护。

Flassger功能众多，接口使用方便，文档丰富，目前处于稳定开发阶段。

随着Swagger向OpenAPI发展，并从2.0向3.0迈进，Flasgger也在跟进开发，感兴趣的开发者可以进一步参与开源贡献。