Support schema introspection

[jmcarp]

The envelope used to serialize responses is implemented in a set of helper methods (format_items, wrap_response, etc.) that could be challenging to introspect (e.g. for building swagger docs). Implementing the envelope using fields and nested schemas would be more amenable to introspection--it should Just Work with apispec.

One option would be adding some magic to Schema--for example, overriding get_declared_fields to replace the original fields with attributes, a Nested that wraps the original fields. This might be too opaque, so we could also define primary schemas separately and explicitly wrap them in JsonSchema classes.

Or maybe this complicates the implementation too much, and it's best to sacrifice purity and just introspect schemas manually--it shouldn't be too hard to write an apispec hook that generates the appropriate markup. The only other caveat there would be that introspection would be brittle, and likely stop working if users subclass Schema and change the envelopes.

Help @sloria!

[sloria]

I'm not necessarily opposed to generating a nested schema if it would simplify introspection. Also, I like the idea of not using @pre_* and @post_* methods in this package (since the order of execution of decorated methods isn't guaranteed). IMO, @pre_ and @post_ belong in userland.

That said, I haven't given much thought to how much this would complicate the internals.

[deckar01]

I expected apispec to "just work", but I ended up with docs representing a simplified marshmallow schema definition instead of docs matching the serialized jsonapi-structured data.

It seems like implementing the jsonapi spec by composing marshmallow_jsonapi out of pure marshmallow fields and schemas would remove the need for @pre/post_* glue.

I image that the implementation will involve transforming the class attributes in the Schema constructor before the super Schema constructor is called. This should eliminate the need for post_dump and change the pre_load to a post_load.

[jeffsawatzky]

Has any progress been made on this? I'm also wondering how you would handle lists. You use the same schema to dump both a single entity as well as multiple entities (with many=True), so how would that work with apispec?

[dperconti]

bump

[sloria]

I would happily review a PR for this, even just a sketch. I don't have time to work on this myself, as I am not currently using this project.

[tjbanks]

Switching to https://github.com/thomaxxl/safrs ended up being my solution, may save others time until this issue is resolved.

[vladmunteanu]

@sloria I've started toying around with this idea here: https://github.com/vladmunteanu/marshmallow-jsonapi-exp/

It's too early for me to tell if schema introspection would work well with this implementation, but I would appreciate some thoughts.