Flask中如何为复合列表构建API模型以在Swagger文档中展示

错误原因 #

fields.List 仅接受1个必填参数，用来指定列表内所有元素的统一类型，你同时传入3个不同字段类型就会触发参数数量不匹配的报错。

解决方案 #

方案1：保留现有有序列表返回结构

你的每个子列表是固定长度3、每个位置类型固定的有序序列，使用fields.Tuple就可以适配这种结构，fields.Tuple支持传入多个字段定义，分别对应序列不同位置的类型：

_results_model = api.model(
    'results model',{
       'results': fields.List(
            # 按顺序定义子列表每个位置的字段类型
            fields.Tuple((
                fields.String(
                    description = 'Name of user',
                    min_length = 6,
                    max_length = 64,
                    pattern = '.*',
                    help = "...",
                    example = 'john.smith'
                ),
                fields.Integer(
                    description = 'Age of user',
                    minimum=0,
                    help = "...",
                    example = 25
                ),
                fields.DateTime(
                    description = 'Date of birth',
                    help = "...",
                    example = '1918-11-11'
                )
            )),
            description="用户列表，每个子项为[姓名, 年龄, 出生日期]的有序序列"
        )
    }
)

如果你的flask-restx版本较低没有内置fields.Tuple，可以临时用fields.List(fields.Raw)替代，在description字段里标注清楚每个位置的类型和含义即可。

方案2（更推荐）：改为结构化对象返回

把每个用户条目从有序列表改成键值对对象，不管是Swagger展示的清晰度，还是前后端联调的可维护性都远高于有序列表，也是API设计的通用惯例。
首先修改接口返回逻辑（顺便修正你原伪代码里results.append(results)的笔误，否则会导致循环引用错误）：

results=[]
for db_row in db_rows:
    result = {
        "name": db_row[0], # Name (string)
        "age": db_row[1], # Age (int)
        "dob": db_row[2] # DOB (timestamp)
    }
    results.append(result)

对应的模型定义：

# 先定义单个用户的字段模型
user_model = api.model(
    'User',
    {
        'name': fields.String(
            description = 'Name of user',
            min_length = 6,
            max_length = 64,
            pattern = '.*',
            help = "...",
            example = 'john.smith'
        ),
        'age': fields.Integer(
            description = 'Age of user',
            minimum=0,
            help = "...",
            example = 25
        ),
        'dob': fields.DateTime(
            description = 'Date of birth',
            help = "...",
            example = '1918-11-11'
        )
    }
)

# 外层结果模型嵌套用户模型列表
_results_model = api.model(
    'results model',
    {
        'results': fields.List(
            fields.Nested(user_model),
            description="用户列表"
        )
    }
)

这种方案后续新增字段不会影响原有逻辑，前端也不需要硬编码索引取值，出错概率低很多。

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