Flasgger 教程：打造你的 Flask 应用Swagger UI

1. 项目介绍

Flasgger 是一个用于 Flask 的扩展，它允许从 Flask 视图中提取 OpenAPI 规范（以前称为 Swagger 2.0），并且集成了 Swagger UI。这使得开发者可以轻松地可视化和交互操作基于 Flask 构建的 RESTful API 资源。Flasgger 提供了数据验证功能，根据定义的 YAML、Python 字典或 Marshmallow Schemas 来检查接收到的数据。它可以处理简单函数视图、MethodViews，甚至可以通过 @swag_from 装饰器获取 YAML 或字典中的规范。

2. 项目快速启动

依赖安装

首先，确保你已经安装了 Python 并创建了一个虚拟环境。在终端中执行以下命令：

# 创建虚拟环境
$ mkvirtualenv my_flask_app

# 进入虚拟环境
$ workon my_flask_app

# 安装所需库
$ pip install flask flasgger

快速示例

接下来，我们将创建一个简单的 Flask 应用并集成 Flasgger。创建一个名为 app.py 的文件，然后添加以下代码：

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

app = Flask(__name__)
Swagger(app)

@app.route('/hello', methods=['GET'])
@swag_from({
    'tags': ['Example'],
    'description': 'Say hello',
    'responses': {
        '200': {
            'description': 'A successful response',
            'examples': {'application/json': {'message': 'Hello, World!'}}
        }
    },
})
def hello():
    return jsonify(message="Hello, World!")

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

运行这个文件，访问 http://localhost:5000/hello 查看 API 功能。要查看 API 文档，打开浏览器访问 http://localhost:5000/apidocs。

3. 应用案例和最佳实践

一个常见的最佳实践是将 API 规范与代码分离。在一个单独的 YAML 文件中定义规范，然后使用 @swag_from 装饰器导入，例如：

# api_docs.yaml
paths:
  /hello:
    get:
      summary: Say Hello
      operationId: say_hello
      responses:
        '200':
          description: Successful response
          schema:
            type: object
            properties:
              message:
                type: string

在 Python 代码中：

# app.py
from flask import Flask, jsonify, request
from flasgger import Swagger
from swag_from_yaml import swag_from_yaml

app = Flask(__name__)
Swagger(app)

with open('api_docs.yaml', 'r') as f:
    SWAGGER_YAML = f.read()

@app.route('/hello', methods=['GET'])
@swag_from_yaml(SWAGGER_YAML)
def hello():
    return jsonify(message="Hello, World!")

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

这样，API 规范更容易管理和维护。

4. 典型生态项目

Flasgger 可以与多个其他开源项目结合使用，如：

• Marshmallow: 用于数据序列化和验证的强大工具。
• Flask-Restplus: 提供更多高级特性，例如模型定义和自动生成 API 级别的文档。
• OpenAPI Generator: 通过 OpenAPI 规范生成客户端库、服务器 stub 和文档。

Flasgger 的核心在于提供了一个界面友好的方式来展示和测试基于 Flask 的 API。与这些生态项目的结合可以进一步增强你的 API 开发体验。