Not enough info on JSON messages in api documentation

[jcpetruzza]

The generated documentation includes an example of the JSON input/output/error messages. This is a great feature but unfortunately it does not currently provide enough usage information when the messages correspond to sum types, which in my case occurs frequently. XML messages do get at least a schema, but we are not using those, so our users have no real way of figuring out how to use the thing.

Ideally, I would show not just one example, but enough of them to sample at least once every possible field that could occur (one needs, I think, only linearly many samples for this, even with nesting). If you were open to such a thing, I could probably come up with a patch for it, but I'd otherwise very much welcome any solution

[bergmark]

Agreed! I think I had some todo for this somewhere that never ended up on github.

I think it would be fairly easy to fix, see Rest.Gen.Base.JSON

Another option is to expose the actual json-schema like we do the xml schema. It might involve creating a json representation for the schema.

We are currently not working on doc generation so contributions are most welcome.

[jcpetruzza]

One catch that I noticed is that schemas for recursive types are infinite objects. So in principle, it is not a good idea neither to try and show a schema directly nor to try to cover all possible constructors (a limit on nesting will be needed). I'm not familiar with the xml case, so I don't know what happens there.

In fact, I suspect the reason why the current setting works at all with recursive (inductive) types is because, when generating the example, it picks the first constructor in the case of sums, which conventionally will be a non-recursive one.