Expose error responses in the spec output

[paulsturgess]

Apia defines errors responses like this:

potential_error 'DiskNotFound' do
  code :disk_not_found
  description 'No disk was found matching any of the criteria provided in the arguments'
  http_status 404
end

So now we declare these in the responses for each endpoint.

https://swagger.io/docs/specification/describing-responses/

closes: #2

---

In swagger:

[paulsturgess]

this file is the same as before, i just decided to create an /authenticators directory and move it there, seeing as i wanted to add some more.

[paulsturgess]

If the schema is blank, then we don't need a $ref for it. This can happen with potential errors when they have no additional fields and thus the detail property is actually just an empty object.

[paulsturgess]

I decided to get rid of the underscores from our ids that we use for component schemas. I thought it looked odd to have camelcase and underscores together. There is no strict format required for these in the spec, but this follows the naming pattern used in the examples.

[paulsturgess]

make rubocop happy

[paulsturgess]

I did think about putting this error response stuff into a separate class. But I thought we might as well keep all the response related logic together in one file.

[paulsturgess]

This is a good example of how the ref naming has changed to remove the underscores

[paulsturgess]

If an endpoint defines many potential errors under the same response code, then we name the $ref id after the route itself, with the status code. This makes the ref unique and ensures it won't accidentally be re-used by other endpoints when the client generator runs.

[paulsturgess]

I needed to add try(:type) in a few places because this schema class can now be called with a Apia::Definitions::Error and that doesn't respond to type.