Support definitions of OpenAPI objects

[ergo]

It would be very helpful if we could somehow generate definitions section of OpenAPI schema, $ref information and providing example values.

One way would be to provide some kind of metadata property on colander schemas with additional information that could be extracted by cornice_swagger and then transformed into proper definitions.

[elbart]

I second that, but am also still puzzled what colander field of a SchemaNode could be used for e.g. the the example. The constructor does not leave some straight-forward option: https://docs.pylonsproject.org/projects/colander/en/latest/api.html#colander.SchemaNode. @ergo interested in a brainstorming session on that?

Update: More research shows, that you can just add more kwargs to a SchemaNode without trouble: https://github.com/Pylons/colander/blob/master/colander/__init__.py#L1938

[elbart]

Just added a PoC. Any opinions by the masters? @Natim @gabisurita @glasserc

[ergo]

Alternatively just expose API for that similar to what apispec does: http://apispec.readthedocs.io/en/latest/quickstart.html#basic-usage, I use it like this in my application: https://github.com/AppEnlight/channelstream/blob/master/channelstream/wsgi_views/server.py#L481

[elbart]

At least for the example case for each of the fields, I'd rather like to have that on the colander.SchemaNode itself. Otherwise you would specify the Schema with Colander and patch examples in on another place. Makes maintenance horrible for bigger projects with many endpoints. But for "patching" more general things of the API Spec, or explicitly adding additional specs (like you did in your example) that might indeed be useful!

Maybe that's more a matter of making the apispec package capable to also read colander schemas?

[rnd0101]

Also, apispec has plugins. The marshmallow one is built-in.