Flask-restx中Put接口同时配置Payload与Query参数的正确方法问询

1. 拆分实现的正确性 #

你当前的拆分写法是完全正确的。在Flask-RESTX（原Flask-RESTPlus）中：

• @api.doc(params=...) 是定义URL查询参数（query params）和路径参数（path params）的标准方式之一，Swagger会正常识别并展示这些参数。
• @api.expect(model, validate=True) 专门用于声明请求体（JSON payload）的模型，配合fields.Raw()只建模外部信封的用法也完全合理，能满足你不对内部payload细节建模的需求。

这种拆分写法是社区常用的规范，只要Swagger能正确显示所有参数（路径、查询、请求体），就没有问题。

2. 整合到单个@api.expect()的方法 #

如果你想把查询参数和请求体整合到同一个@api.expect()调用中，可以通过RequestParser来定义查询参数，然后将模型和解析器一起传入@api.expect()：

修改后的代码示例 #

class WBRTRoutes():

    @staticmethod
    def bind(api):
        ns_workareas = api.namespace("workareas", description = "Registered workareas")
            
        mod_workarea_update = api.model("WorkareaUpdate", {
            "workarea":  fields.Raw(description = "the workarea object")
            })

        mod_details = api.model("Details", {
            "details": fields.List(fields.String)
            })

        # 注：原代码中mod_version未定义，假设为已存在的模型
        resp_version = api.model("RspVersion", {
            "message":   fields.String(description = "used to return message to the caller"),
            "data":      fields.Nested(mod_version, description = "the incremented version after an update", skip_none = True)
            })
        
        # 用RequestParser定义查询参数
        query_parser = api.parser()
        query_parser.add_argument('workid', type=str, location='args', help='The internal workarea identifier')

        @ns_workareas.route('/<workid>')
        @api.doc(description='Represents a registered workarea by its workid')
        class Workarea(Resource):
            # 同时传入请求体模型和查询参数解析器
            @api.expect(mod_workarea_update, query_parser, validate=True)
            @api.marshal_with(resp_version)
            @api.response(200, 'Success')
            @api.response(403, 'Forbidden')
            @api.response(404, 'Resource not found')
            def put(self, workid):
                """Performs an undoable update to current a workarea, after checking for interleaved updates"""
                # 获取查询参数：args = query_parser.parse_args()
                pass

说明 #

• api.parser()创建的解析器会自动在Swagger中生成查询参数的文档。
• @api.expect()可以接受多个参数（模型、解析器），只要参数类型正确，Swagger就能同时展示请求体和查询参数。
• 路径参数workid依然通过路由/<workid>定义，无需额外处理，Swagger会自动识别。

两种方式的对比 #

• 拆分写法：更清晰，区分了路径/查询参数和请求体，适合参数较少的场景。
• 整合写法：将所有请求参数的声明集中到@api.expect()中，适合参数较多或希望集中管理的场景。

两种写法都是合法且规范的，可根据项目风格选择。

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