Change OpenAPIConverter into OpenAPIConverterMixin

[lafrech]

What I suggested in #478 (comment).

This makes it easier to subclass MarshmallowPlugin.

[sloria]

I'm good with this. It makes MarshmallowPlugin quite fat, but I think it's worth it for the ease of extensibility.

[sloria]

An alternative approach would be to set the converter as a class member on MarshmallowPlugin.

class MarshmallowPlugin(BasePlugin):
    Converter = OpenAPIConverter

The plugin can be extended like so:

class MyMarshmallowPlugin(MarshmallowPlugin):
    class Converter(MarshmallowPlugin.Converter):
        def property2parameter(self, ...):
            ...

wdyt?

[lafrech]

Thanks for the doc update.

Mixin vs. class member is a matter of taste. Both work.

With class member, subclassing just takes one more line. Neglectable.

I have no issue with the plugin class being fat since the mixin is in another file, like if it was another class.

(I don't know if you ever looked at flask-rest-api. I separated the features using mixins. I'm not sure those are real mixins like mixins are meant for, it's hard because the features are not strictly independent. But it makes for a nice split of the code.)

Perhaps the mixin here makes sense because it avoids passing the schema_name_resolver from the plugin to the converter, or fetching the refs in the converter from the plugin, and so on. The separation is not clear enough to do things nicely with a separate class.

[sloria]

I have no strong preference. Things can get confusing when inheritance chains get long with lots of mixins (at work we're considering running with the nested class approach in our REST framework), but that's not a problem here.

(I don't know if you ever looked at flask-rest-api. I separated the features using mixins.

werkzeug organizes things this way, too: https:/pallets/werkzeug/blob/9844e0447e63366273c8b9f9f2400e19b45532d1/src/werkzeug/wrappers/request.py#L9-L16 . It's a nice way to split up the code.

So long as you're OK with publicizing all these methods, let's go ahead with this.

[lafrech]

So long as you're OK with publicizing all these methods, let's go ahead with this.

The point is to make subclassing easier. I suppose allowing users to subclass means we're considering it public, either way (be it mixin or class member).

Should we remove the docstrings in openapi.py and field_converter.py saying the module is private API?

[sloria]

I guess the class member way makes the methods "semi-private", as in you can still override them if you know what you're doing, but the converter class itself can remain documented as private/subject to change.

Should we remove the docstrings in openapi.py and field_converter.py saying the module is private API?

We could just remove :inherited-members: from the apispec.ext.marshmallow autodoc in api_ext.py. Your call on this.

[lafrech]

Closing in favor of #493.