Flasgger – 为Flask快速生成Swagger文档

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

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

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

而 ，把 带给了 Flask。

框架

简介

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

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

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

框架

安装

使用 pip 安装即可：

pip install flasgger

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

pip install marshmallow apispec

示例

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

from flask import Flask, jsonify
from flasgger import Swagger
app = Flask(__name__)
swagger = Swagger(app)
@app.route('/colors//')
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 应用例子，我们定义了一个接口，它接受色调参数，返回颜色的列表。

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

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

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

界面

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

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

参数定义

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

接口测试

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

类型

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

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

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

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

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

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 的方式，这里直接引用了的来进行数据类型的定义

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

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

框架

总结

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

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

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

———END———
限 时 特 惠： 本站每日持续更新海量各大内部创业教程，永久会员只需109元，全站资源免费下载 点击查看详情
站 长 微 信： nanadh666