使用Flask-Restful+apispec+marshmallow时如何设置字段示例值？

方法1：使用Marshmallow字段的example参数（推荐） #

Marshmallow 3.x及以上版本支持直接给字段添加example参数，apispec会自动识别该参数并生成Swagger示例值。修改你的request_schema.py：

# request_schema.py
from marshmallow import Schema, fields

class RequestSchema(Schema):
    name = fields.Str(required=True, example="John Doe")  # 直接添加示例值

方法2：通过字段的metadata字典设置 #

如果你的Marshmallow版本较低，或者需要附加其他元数据，可以用metadata参数传入示例值：

# request_schema.py
from marshmallow import Schema, fields

class RequestSchema(Schema):
    name = fields.Str(required=True, metadata={"example": "John Doe"})

方法3：为整个Schema设置完整示例（可选） #

如果需要给整个请求体设置完整的示例结构，可以在Schema类中定义class Meta并添加example属性：

# request_schema.py
from marshmallow import Schema, fields

class RequestSchema(Schema):
    name = fields.Str(required=True)

    class Meta:
        example = {
            "name": "John Doe"
        }

验证基础配置 #

确保你的Flask-Apispec已正确集成Marshmallow插件，初始化代码示例如下（如果尚未配置）：

# 示例初始化代码
from apispec import APISpec
from apispec.ext.marshmallow import MarshmallowPlugin
from flask_apispec.extension import FlaskApiSpec
from flask import Flask

app = Flask(__name__)
app.config.update({
    'APISPEC_SPEC': APISpec(
        title='你的API名称',
        version='v1',
        plugins=[MarshmallowPlugin()],
        openapi_version='2.0'
    ),
    'APISPEC_SWAGGER_URL': '/swagger/'  # Swagger UI访问地址
})
docs = FlaskApiSpec(app)

# 注册你的API资源
docs.register(Restful_Request)

完成以上修改后重启服务，Swagger页面的对应字段就会显示你设置的示例值了。

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