Represent Response with sideloading

[frankietaylor]

We want to use swagger for documentation generation and also for the convenience that client code gets generated from swagger output.

We are adhering to JSON:API specification for the models. It has the concept of side-loading related models along with the main data. For example, when fetching articles models, we can ask to include corresponding authors' models for each article in a single api call.

How to represent this in Swagger?

[ePaul]

Swagger/OpenAPI currently (in version 2.0) doesn't really support different result schemas depending on parameters (or on different criteria like content types or similar).

So the best you can do is to declare the model schema with the related objects included, set required: false for those properties, and explain the relation in plain text in the description (of model and/or operation).

For the next version, on which we are currently working, there are several related issues: #270, #164, #146.

[webron]

Closing as replied and referenced to the relevant tickets.