registry.add_supplemental_schemas

[joeb1415]

Add registry.add_supplemental_schemas function to export supplemental schemas to swagger, in addition to those used by the API handlers.

In my app, I have a handler:

@registry.handles(
    marshal_schema={201: FooSchema}
)
def create_foo():
    pass

With:

class FooSchema(Schema):
    template = fields.String()
    vars = fields.Dict()

Elsewhere, I validate the vars against the template according to various template schemas:

class Template_1_Schema(Schema):
    var_1 = fields.String()
    var_2 = fields.String()

class Template_2_Schema(Schema):
    var_3 = fields.Boolean()
    var_4 = fields.Integer()

I would like to export these template schemas in the swagger definition, so others can know what to expect to send to my handler in the vars dictionary param.

This PR introduces a registry function add_supplemental_schemas to support this. The function can accept a single schema, or for convenience, a directory containing all the supplemental schemas.

cc: @barakalon

[brockhaywood]

@joeb1415 Just curious, why does vars need to be a Dict field and not a nested schema referencing Template_1_Schema? still see the value in being able to reference other models just curious about this particular use case.

[joeb1415]

@brockhaywood There are many template / schema pairs, with different schemas. I added a second example to my PR comment above to make this clearer.

[brockhaywood]

Ah got it, conditional templates?

[barakalon]

It seems like what you actually want is the discriminator field: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schema-object

But this field sucks. And OpenAPI 3.0 replaces this with the proper jsonSchema way of doing this: oneOf.

If you had one of these features available, would you need this change? I'd rather avoid things that both require manual tweaking of the swagger, especially those that aren't really sanctioned in the swagger spec. But I prefer practicality over purity, so I'm open to this change if we really need it.

[colinhostetter]

Did you look into the possibility of just adding these schemas into the client package we generate / did that not work?

I'm not sure this belongs in rebar, and I'm not sure that adding it to rebar actually gets us anything over doing that, since the generated client won't know which template schema to validate against either way. (Well, I guess it adds a little consistency in that the schemas in the package are the regular swagger-codegen schemas instead of Marshmallow schemas, hmm...)

[joeb1415]

@barakalon yeah if we could do something like this that would be awesome!

class FooSchema(Schema):
    template = fields.String()
    vars = fields.Nested(Schema, validate=OneOf(Template_1_Schema, Template_2_Schema))

[joeb1415]

This looks interesting:
https://github.com/marshmallow-code/marshmallow-oneofschema

[barakalon]

That seems to be the blessed one: marshmallow-code/marshmallow#649

Doesn't seem too bad to add a converter that uses the discriminator field for OneOfSchema here: https://github.com/plangrid/flask-rebar/blob/master/flask_rebar/swagger_generation/marshmallow_to_swagger.py

However, since OneOfSchema comes from a separate package, dependency management gets a little hairier. We'd probably want to add something like:

try:
    from marshmallow_oneofschema import OneOfSchema
    # define converter, register it
except ImportError:
    pass

Or make it a separate plugin.
Or just add a recipe for the code in documentation, and expect people that need it to add it to copy/paste it into their own application.

[RookieRick]

Hey folks, sorry I'm late to the party here (having just joined the team :D) - Doing some PR housekeeping.. If I've followed the conversations accurately, is it fair to say this will get rolled in with OpenAPI 3.0 support WIP?
cc @joeb1415

[RookieRick]

Closing in favor of OpenAPI 3.0 support which should make this irrelevant