Flask API 项目 Swagger 版本打架不兼容

Flask API 项目 Swagger 版本打架不兼容

1. 问题背景

在使用 Flask 3.0.0 时遇到以下问题：

• 安装 flask_restful_swagger 时，它强制将 Flask 降级到 1.1.4，并导致其他依赖（如 flask-sqlalchemy、flask-apispec）出现版本冲突。
• 需要解决 Flask 版本兼容问题，并且集成 Swagger API 文档。

2. 问题分析

• flask_restful_swagger 是一个较为过时的库，已经不再更新，且与 Flask 3.x 版本不兼容。
• flask-sqlalchemy 和 flask-apispec 需要 Flask >= 2.2.5 版本，而 flask_restful_swagger 安装时强制降级 Flask 版本会导致兼容性问题。

3. 解决方案

为了解决版本冲突，采用以下方案：

1. 安装 flask_restful_swagger 时会降级 Flask 版本：
   • 在项目中，使用 flask_restful_swagger 的版本 0.20，它将 Flask 版本降级到 1.1.4。
2. 手动解决版本冲突：
   • 安装完成后，立即 卸载 Flask 1.1.4 并安装 Flask 3.0.0，否则 flask-sqlalchemy、flask-apispec 等插件会报错。

   具体步骤如下：

步骤一：安装兼容包

安装 flask_restful_swagger 最新版本（0.20）：

pip install flask_restful_swagger

步骤二：安装Flask

卸载 Flask 1.1.4：

pip uninstall flask

安装 Flask 3.0.0：

pip install flask==3.0.0

步骤三：配置 Flask 和 Flask-APISpec

应用配置 (__init__.py)：

在程序文件 __init__.pyy 中进行以下配置：

from flask import Flask
from flask_apispec import FlaskApiSpec
from flask_restful import Api, Resource
from flask_sqlalchemy import SQLAlchemy
from flask_restful_swagger import swagger
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin

# 实例化 Flask 应用
app = Flask(__name__)

# 配置 OpenAPI 和 Swagger 文档
app.config.update({
    'APISPEC_SPEC': APISpec(
        title='My API',
        version='v1',
        plugins=[MarshmallowPlugin()],
        openapi_version='2.0.0'
    ),
    'APISPEC_SWAGGER_URL': '/swagger/',  # Swagger JSON
    'APISPEC_SWAGGER_UI_URL': '/swagger-ui/'  # Swagger UI
})

# 实例化 Flask-RESTful API
api = Api(app)
db = SQLAlchemy(app)

# 配置 FlaskApiSpec 用于注册 Swagger 文档
docs = FlaskApiSpec(app)

步骤四：定义资源和路由

通过使用 Flask-RESTful 和 flask-apispec 来定义 API 资源，并添加 Swagger 文档注解。

API 资源类：

class UserResource(Resource):
    @doc(description="获取用户详情"，tags=[Book Resource])  # 文档注解
    def get(self):
        return {"message": "Hello, World!"}

将资源添加到 API：

api.add_resource(BookResource, '/books/<int:book_id>')
docs.register(BookResource)  # 注册到 API 文档

上面代码中，@doc 注解为该接口生成文档说明，docs.register() 将资源添加到 Swagger 文档中。

步骤五：访问 Swagger 文档

• 启动 Flask 应用后，访问 http://127.0.0.1:5000/swagger-ui/ 来查看自动生成的 Swagger UI。
• http://127.0.0.1:5000/swagger/ 返回的是 Swagger JSON 文档。

image-20250421164513411

4. 总结

• 通过手动卸载并重新安装 Flask 3.0.0，结合 flask-apispec，可以解决 flask_restful_swagger 与 Flask 3.0.0 的版本冲突问题，并实现现代的 API 文档生成功能。
• 完整流程：
  1. 安装 flask_restful_swagger，它会将 Flask 降级到 1.1.4。
  2. 卸载 Flask 1.1.4 并重新安装 Flask 3.0.0。
  3. 配置 Flask 和 Flask-APISpec 以生成 Swagger 文档。
  4. 定义 API 资源和路由，并通过 Swagger 生成 API 文档。