Support documentation of complex types

[Guillaume Boivin]

Hi,

I'm going to expose one functionality that, in my opinion, could be beneficial to Taffy. If you agree, or not, please comment this post. Thanks in advance.

Currently, if you have an argument of an operation (let's say a post operation of a contact resource) for one of your resource that is a a structure of data (aka complex type), you have no way of documenting the details of this structure.

So the functionality would be to add a way for each argument of an operation of a resource (so, get, put, post, etc... of the contact resource for example) to put more detailed information about the structure of each f those argument when this argument is a complex type. That way we could auto-document it and be able to generate a template request in the dashboard. 

Here is an example using a cfc as the mean of explaining the complex type of the contact resource (could be an other mean, just used here for the example)  :

The json representation of the request data for this example would be :

{
  "firstname" : "bob",
  "lastname" : "smith",
  "father" : {
    "firstname" : "john",
    "lastname" : "smith"
  }
}

Currently, this use case can not be properly documented/mocked via the dashboard, as complex types are not supported. You could put an hint on the father argument, but that in my opinion is using the attribute in a way it was not meant to be used (explaining more than one argument that is).

An issue as been filed on github too with additional info.