Flasgger 使用教程-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01125/article/details/141043734

Flasgger 使用教程

flasggerEasy OpenAPI specs and Swagger UI for your Flask API项目地址:https://gitcode.com/gh_mirrors/fl/flasgger

项目介绍

Flasgger 是一个 Flask 扩展，用于从 Flask 应用中提取 OpenAPI 规范，并提供 Swagger UI 以便用户可以直观地查看和交互 API 资源。Flasgger 支持通过 YAML、Python 字典或 Marshmallow 模式进行数据验证，确保传入的数据符合定义的 schema。

项目快速启动

安装 Flasgger

首先，创建一个虚拟环境并激活它：

mkvirtualenv test_api

然后安装 Flask 和 Flasgger：

pip install flask flasgger

创建一个简单的 Flask 应用

创建一个名为 simple_test.py 的文件，并添加以下代码：

from flask import Flask, jsonify, request
from flasgger import Swagger

app = Flask(__name__)
Swagger(app)

@app.route('/api/<string:language>/', methods=['GET'])
def index(language):
    """
    这是一个语言特性 API
    调用此 API 并传递语言名称以获取其特性
    ---
    tags:
      - 语言特性
    parameters:
      - name: language
        in: path
        type: string
        required: true
        description: 语言名称
    responses:
      200:
        description: 返回语言特性
    """
    features = {
        'Python': '动态类型',
        'Java': '静态类型',
    }
    return jsonify({language: features.get(language, '未知语言')})

if __name__ == '__main__':
    app.run(debug=True)

运行应用：

python simple_test.py

访问 http://localhost:5000/apidocs 可以看到 Swagger UI。

应用案例和最佳实践

使用 YAML 定义 API

Flasgger 支持在 docstring 中使用 YAML 来定义 API 规范。以下是一个示例：

@app.route('/api/feature', methods=['POST'])
def feature():
    """
    This is the feature API
    Call this api passing a language name and get back its features
    ---
    tags:
      - 特性
    parameters:
      - name: body
        in: body
        required: true
        schema:
          id: feature
          required:
            - language
          properties:
            language:
              type: string
              description: 语言名称
              default: Python
    responses:
      200:
        description: 返回语言特性
    """
    data = request.json
    language = data['language']
    features = {
        'Python': '动态类型',
        'Java': '静态类型',
    }
    return jsonify({language: features.get(language, '未知语言')})

使用 Marshmallow 进行数据验证

Flasgger 支持使用 Marshmallow 进行数据验证。以下是一个示例：

from flask import Flask, jsonify, request
from flasgger import Swagger, swag_from
from marshmallow import Schema, fields

app = Flask(__name__)
Swagger(app)

class FeatureSchema(Schema):
    language = fields.Str(required=True)

@app.route('/api/feature', methods=['POST'])
@swag_from('feature_schema.yml')
def feature():
    schema = FeatureSchema()
    errors = schema.validate(request.json)
    if errors:
        return jsonify(errors), 400
    data = request.json
    language = data['language']
    features = {
        'Python': '动态类型',
        'Java': '静态类型',
    }
    return jsonify({language: features.get(language, '未知语言')})

if __name__ == '__main__':
    app.run(debug=True)