如何在Flask-restx的Swagger UI中自动使用Marshmallow Schema配置参数

核心思路是给Marshmallow的Schema基类扩展自定义类方法，自动读取字段的类型、描述、校验规则、必填属性，生成符合flask-restx @ns.doc 要求的参数字典。

第一步：自定义Schema基类，扩展参数转换方法 #

from marshmallow import Schema, fields

class BaseSchema(Schema):
    @classmethod
    def to_params_dict(cls):
        params = {}
        for field_name, field_obj in cls._declared_fields.items():
            desc_parts = []
            # 拼接字段类型
            desc_parts.append(f"类型: {field_obj.__class__.__name__}")
            # 拼接自定义描述
            if field_obj.metadata.get("description"):
                desc_parts.append(field_obj.metadata["description"])
            # 拼接必填标识
            if field_obj.required:
                desc_parts.append("*必填*")
            # 拼接校验规则
            for validator in field_obj.validators:
                # 适配数值范围校验
                if hasattr(validator, "min") and hasattr(validator, "max"):
                    desc_parts.append(f"取值范围: {validator.min} ~ {validator.max}")
                # 适配字符串长度校验
                elif hasattr(validator, "min_length") and hasattr(validator, "max_length"):
                    desc_parts.append(f"长度范围: {validator.min_length} ~ {validator.max_length}字符")
            params[field_name] = " | ".join(desc_parts)
        return params

第二步：业务Schema继承自定义基类 #

class MySchema(BaseSchema):
    title = fields.Str(description="字符串类型标题")
    id = fields.Integer(description="整数ID", required=True, validate=lambda x: 1<=x<=10000)
    slug = fields.Str(description="URL别名", validate=fields.Length(min=2, max=50))

第三步：接口直接调用方法生成文档参数 #

@ns.route('/')
class Test(Resource):
    # 直接调用Schema的类方法生成params配置，无需手动编写
    @ns.doc(params=MySchema.to_params_dict())
    def get(self):
        _input_schema = MySchema()
        errors = _input_schema.validate(request.args)
        if errors:
            return Response(str(errors), status=400)
        other_things()

如果需要适配POST请求体、响应模型的自动同步，只需要在BaseSchema中新增对应的类方法，按照flask-restx要求的格式读取字段属性生成对应配置即可。

内容的提问来源于stack exchange，提问作者Angus G.