Return object schemas are descriptive so that generated clients are more user friendly

[telday]

Currently the requests which return a JSON object to the user are simply specified in the OpenAPI spec as returning an "object". For example the secrets endpoint has SecretBatchValue specified as the endpoint which only specifies that the value returned is a JSON object. We should expand this to actually describe the object that will be returned. This should make the generated clients more user friendly. A good example of a complete schema is HostFactoryTokenRequest.

AC:

• All response schema are properly described
  • secrets file
  • policies file
  • roles file
  • host_factory_tokens file
  • resources file
  • authentication file
  • cert-auth file
  • public-keys file
  • status file
• Each endpoint returning an object has a proper example included
  • secrets file
  • policies file
  • roles file
  • host_factory_tokens file
  • resources file
  • authentication file
  • cert-auth file
  • public-keys file
  • status file

[john-odonnell]

Found a slight issue with this effort while working on issue #65.

The response for a get request to /roles/{account}/{kind}/{identifier} has a different schema depending on query params:

• without query params, or with count, the server response body is a JSON object
• with any of the other query params, the server response body is an array of JSON objects

This might make it difficult to generalize this endpoint's return schema.

EDIT: another note on this

Tried to implement some schema polymorphism to the Roles responses, which is the method that OpenAPI v3 docs suggests for handling this (OpenAPI docs on polymorphism).

Turns out this is one of the few functions not supported by OpenAPITools' OpenAPI Generator (OpenAPI Generator docs on supported schema features).