Flask如何定义纯空列表类型的fields model适配Swagger UI展示

你之前用api.model()定义的是JSON对象（字典结构）的模型，所以会自动生成外层的键值对结构。要实现纯列表的请求/响应结构，不需要用api.model包裹对象，直接将fields.List作为顶级模型使用即可，同时通过example参数指定Swagger UI的默认展示内容。

具体实现代码 #

1. 定义纯列表模型

from flask_restx import fields

# 元素为字符串的纯列表模型，example指定默认展示为空列表
config_list_model = fields.List(fields.String(required=True), example=[])

如果你的列表元素是复杂对象，可以嵌套已定义的model：

# 先定义列表内的元素模型
config_item_model = api.model('ConfigItem', {
    'config_key': fields.String(required=True),
    'config_value': fields.String(required=True)
})
# 元素为上述对象的纯列表模型
config_list_model = fields.List(fields.Nested(config_item_model), example=[])

2. 在路由中使用
   如果是用作请求体校验：

@api.route('/config/update')
class ConfigUpdate(Resource):
    # 直接传入定义好的列表模型即可
    @api.expect(config_list_model, validate=True)
    def post(self):
        # 此时api.payload直接拿到列表数据，没有外层字典
        config_list = api.payload
        # 后续业务逻辑
        return {"code": 200, "msg": "success"}

如果是用作响应序列化：

@api.route('/config/list')
class ConfigList(Resource):
    @api.marshal_with(config_list_model)
    def get(self):
        # 直接返回列表结构即可
        return [{"config_key": "a", "config_value": "b"}, {"config_key": "c", "config_value": "d"}]

效果说明 #

按上述写法配置后，Swagger UI中的请求/响应默认示例会直接展示为空列表[]，完全符合你的业务需求。

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