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 等插件会报错。

   具体步骤如下：

步骤一：安装兼容包

1. 安装 flask_restful_swagger 最新版本（0.20）：

   pip install flask_restful_swagger
   

步骤二：安装Flask

1. 卸载 Flask 1.1.4：

   pip uninstall flask
   

2. 安装 Flask 3.0.0：

   pip install flask==3.0.0
   

步骤三：配置 Flask 和 Flask-APISpec

1. 应用配置 (__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 文档注解。

1. API 资源类：

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

2. 将资源添加到 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 文档。

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 文档。
     wagger`**，它会将 Flask 降级到 1.1.4。
  4. 卸载 Flask 1.1.4 并重新安装 Flask 3.0.0。
  5. 配置 Flask 和 Flask-APISpec 以生成 Swagger 文档。
  6. 定义 API 资源和路由，并通过 Swagger 生成 API 文档。