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

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 开发体验。