Add JSON Response Schemas

[wsugarman]

While the examples on the API docs page (Eg. the member responses) are helpful, they do not have the exact schema information, nor are they always up-to-date. It would be great if the latest response schemas were available online and complete with type information. For example, it would be really helpful to know the range for numeric IDs or even the possible values for a given string: is there a set of valid strings, a regex, or could it be anything?

JSON schemas would remove any ambiguity of what to expect.

[ndawg]

I think this would be good for a V2 of the API. A lot of the responses could be reworked to be structured much better and to be more consistent in general. @dwillis is this something you guys would be interested in pursuing?

[dwillis]

@ndawg Yeah, that seems doable.

[wsugarman]

Perhaps the documentation could leverage the OpenAPI Specification 3.0 for detailing request and response schemas.

[ndawg]

Definitely agree, OpenAPI spec is the way to go. It's a widely used standard, and it allows codegen and other features.