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. 解决方案

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

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

步骤一：安装兼容包

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

  复制代码

步骤二：安装Flask

• 卸载 Flask 1.1.4：
  1. pip uninstall flask

  复制代码
• 安装 Flask 3.0.0：
  1. pip install flask==3.0.0

  复制代码

步骤三：配置 Flask 和 Flask-APISpec

• 应用配置 (__init__.py)：
  在程序文件 __init__.pyy 中进行以下配置：
  1. from flask import Flask
  2. from flask_apispec import FlaskApiSpec
  3. from flask_restful import Api, Resource
  4. from flask_sqlalchemy import SQLAlchemy
  5. from flask_restful_swagger import swagger
  6. from apispec import APISpec
  7. from apispec.ext.marshmallow import MarshmallowPlugin
  9. # 实例化 Flask 应用
  10. app = Flask(__name__)
  12. # 配置 OpenAPI 和 Swagger 文档
  13. app.config.update({
  14.     'APISPEC_SPEC': APISpec(
  15.         title='My API',
  16.         version='v1',
  17.         plugins=[MarshmallowPlugin()],
  18.         openapi_version='2.0.0'
  19.     ),
  20.     'APISPEC_SWAGGER_URL': '/swagger/',  # Swagger JSON
  21.     'APISPEC_SWAGGER_UI_URL': '/swagger-ui/'  # Swagger UI
  22. })
  24. # 实例化 Flask-RESTful API
  25. api = Api(app)
  26. db = SQLAlchemy(app)
  28. # 配置 FlaskApiSpec 用于注册 Swagger 文档
  29. docs = FlaskApiSpec(app)

  复制代码

步骤四：定义资源和路由

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

• API 资源类：
  1. class UserResource(Resource):
  2.     @doc(description="获取用户详情"，tags=[Book Resource])  # 文档注解
  3.     def get(self):
  4.         return {"message": "Hello, World!"}

  复制代码
• 将资源添加到 API：
  1. api.add_resource(BookResource, '/books/<int:book_id>')
  2. 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 文档生成功能。
  
• 完整流程：
  
  
  • 安装 flask_restful_swagger，它会将 Flask 降级到 1.1.4。
    
  • 卸载 Flask 1.1.4 并重新安装 Flask 3.0.0。
    
  • 配置 Flask 和 Flask-APISpec 以生成 Swagger 文档。
    
  • 定义 API 资源和路由，并通过 Swagger 生成 API 文档。
    
  
  

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！