marshmallow

Add a description to a field in Marshmallow


How can I add a field comment or description in Marshmallow?

I want to show it in something like Apispec.


Solution

  • This is an existing but undocumented feature of APISpec's Marshmallow extension. If your Marhshmallow field has any of the properties in this list, APISpec will use it in the generated Swagger specifications. For example, I have this as one of my schema definitions:

    class ErrorSchema(Schema):
        code = fields.Int(description="An API specific Error code", required=True)
        message = fields.String(description="A user readable message")
    

    which results in APISpec generating the following:

    ErrorSchema {
    message (string, optional): A user readable message,
    code (integer): An API specific Error code
    }