marshmallow/swagger.py - custom field mapping

[lafrech]

Hi.

Assuming a model uses custom Marshmallow fields, those do not appear in FIELD_MAPPING and therefore are not documented properly: default (type, format) is ('string', None).

If _get_json_type_for_field used isinstance rather than type, fields inheriting from Marshmallow fields would at least be treated like their parent, but this wouldn't be totally satisfying.

OpenAPI spec allows custom formats for fields, like apispec does Email, for instance,

marshmallow.fields.Email: ('string', 'email'),

Is there a way to pass custom field mappings to apispec?

If not, would this be considered a relevant feature request?

A list of custom types ((CUSTOM_FIELD_MAPPING) could be appended to FIELD_MAPPING. Or better, CUSTOM_FIELD_MAPPING would be checked first, so as to allow overriding existing mappings in FIELD_MAPPING.

[lafrech]

Well, since nothing prevents me from importing FIELD_MAPPING and modifying it in my own application, this question is not that relevant. I guess I was making things too complex...

from apispec.ext.marshmallow.swagger import FIELD_MAPPING

class MyDocClass(object):

    def register_field(self, field, field_type, field_format):
        FIELD_MAPPING[field] = (field_type, field_format)

[lafrech]

One last thing, though: is it safe to import and modify FIELD_MAPPING? I mean is it considered part of the API or may it be renamed/removed in a future version?

I believe the use case is valid, so it would make sense to consider this object part of the API, and consider its modification/removal as a breaking change (or alternatively provide a function in the API to wrap it).

More generally, is there some sort of convention in Python about what objects in a lib are part of the API and can be safely imported? Any way to know for sure? Like,

• it is documented as such
• changing it would break a test
• it appears in __all__ somewhere
• it is imported or created in top level module

[sloria]

It is perfectly valid to modify FIELD_MAPPING.

More generally, is there some sort of convention in Python about what objects in a lib are part of the API and can be safely imported? Any way to know for sure?

I'm not sure there's any documented convention, but the list you have above is a good rule of thumb.