Support attribute enumeration for targetSchema

[duckpunch]

When describing the response in Markdown, prmd only provides an example. It'd be great to enumerate the attributes of the targetSchema like it is enumerated for the request parameters.

I wasn't sure if this is something that would be palatable. If it is, I'd be happy to submit a PR (or just wait for an update!)

[geemus]

I guess we hadn't really considered that too much as we tend to have parity between the properties of the resource and what is in the example (so it seemed redundant to list it again in the response when it was already available elsewhere). Maybe we should make that more explicit or link though. That said, could you provide a more explicit/concrete example of what you think the schema and output might look like? I think that could really help make sure we are on the same page before we deal with implementation details. Thanks!

[duckpunch]

Good point about the parity that naturally happens. That kills some of the use cases I had in mind :P

We're using JSONAPI which can sometimes have pretty complicated responses. One use case for enumerating attributes is when describing errors. This might be conflating #295.

Here's an example snippet of a response which is a JSONAPI error object that might be returned after a POST. The example is for a validation error which is difficult for the client to detect upon submission.

{
  "errors": [
    {
      "code": "overlapping-time-range",
      "detail": "Entry with time range (A, B) causes an overlap with an existing record"
    }
  ]
}

It'd be neat if the documentation could enumerate the codes like the other enums. Further, it would be useful to know what kind of details would be provided. There are also other fields that could use a description beyond the JSONAPI spec.

[geemus]

Yeah. It might fit to do something in this area using something like oneOf to show that it could be one of the errors or the expected thing, but I don't think it would be setup to "just work" at this point. Plus we would need to think about how the output would appear in that case. I guess I worry a bit that it might get really verbose, really quickly. The way we have handled this has been to have a portion of introductory text that explains the common error patterns you might expect, but then doesn't repeat/expand upon them in the particular cases. Does that make sense/help at all? It may well be time to revisit/expand on that though.

[duckpunch]

That makes sense.

Maybe using oneOf, we could provide $ref links which link to HTML anchors defining the error. This would probably require defining errors more rigorously.

[geemus]

Interesting, yeah that sounds like a good balance between individual specificity and not duplicating a bunch of stuff.