如何合并Flask中flasgger与flask_restx生成的Swagger文档

两种技术栈开发的接口完全支持合并为统一文档页，无底层冲突，以下是按改造成本从低到高排序的可落地方案：

方案1：零业务代码改造，统一收敛到flasgger文档页 #

这个方案不需要修改任何已经写好的接口逻辑，10分钟就能完成合并，适合短期快速收口文档的场景。
核心原理是flasgger支持自定义全局OpenAPI规范，直接把flask_restx生成的接口规范动态合并进去即可。

1. 首先关闭flask_restx自带的独立文档页，初始化Api实例时传入doc=False参数，避免出现两个文档入口：

from flask_restx import Api
# 原有restx初始化代码加doc=False即可
restx_api = Api(your_blueprint, doc=False)

2. 初始化flasgger时，动态拉取flask_restx生成的接口规范，和flasgger自身收集的swag_from规范做合并，不需要手动导出json文件：

from flasgger import Swagger
from flask import Flask

app = Flask(__name__)

# 等所有路由注册完成后，再初始化Swagger做合并
def init_merged_swagger(app):
    # 直接从restx实例拿到自动生成的完整接口规范，无需手动请求接口
    restx_spec = restx_api.__schema__
    # 合并两边的路径、模型定义
    merged_template = {
        "title": "项目统一API文档",
        "version": "1.0.0",
        "paths": restx_spec.get("paths", {}),
        "definitions": restx_spec.get("definitions", {}), # 适配Swagger2.0
        "components": {"schemas": restx_spec.get("components", {}).get("schemas", {})} # 适配OpenAPI3.0
    }
    # 初始化flasgger，所有文档统一在原/apidocs/路径展示
    Swagger(app, template=merged_template)

# 注意要在所有Blueprint、路由都注册完成后再调用这个初始化方法
init_merged_swagger(app)

3. 启动项目后访问原flasgger的/apidocs/地址，就能同时看到两类接口的文档。

方案2：长期维护方案，统一收敛到flask_restx文档页 #

如果团队后续计划统一用flask_restx作为API开发栈，可以把原有swag_from定义的接口规范迁移到flask_restx中，统一用restx自带的文档页展示，长期维护成本更低：

• 第一步：收集所有@swag_from装饰器引用的yaml/json格式接口规范
• 第二步：将这些规范转换为flask_restx支持的Namespace、Model格式，逐批注册到restx的Api实例中
• 第三步：关闭flasgger自带的文档路由，所有接口规范统一由flask_restx管理，最终文档统一在restx配置的根路径展示

注意事项 #

• 合并前先统一OpenAPI版本：flasgger默认使用Swagger2.0规范，如果flask_restx配置了OpenAPI3.0，需要同步把flasgger的openapi参数设为3.0.0，否则会出现模型解析异常、参数展示错误的问题
• 提前排查重复接口：合并前检查两边的paths字段，避免出现同HTTP方法、同路径的重复接口条目
• 不建议长期双栈并存：双栈维护需要每次改接口同步两份规范，很容易出现文档和实际逻辑不一致的问题，建议排期逐步统一技术栈

内容的提问来源于stack exchange，提问作者JustLearning