client-generator

- A new `bin/heroics-generate` script renders a Ruby client built from
  a JSON schema.  Given a Heroku Platform API schema you can render a
  client for Heroku with:

  ```
  bundle exec bin/heroics-generate PlatformAPI schema.json https://api.heroku.com > myclient.rb
  ```

  The entire client, including a baked in copy of the schema, is
  written to a single file.  Right now the version and cache options
  are hard-coded in `bin/heroics-generate`.  Suggestions on how we
  should accept these kinds of values would be appreciated.  So far
  I've tried to avoid a configuration file, preferring to pass all
  options on the command-line, but it seems like that'll be pretty
  ugly for these bits.

- A new `Heroics.generate_client` method takes a `Heroics::Schema`
  instance, along with some basic configuration information, and
  renders client code.  It's using Erubis and a template to do so.
  API documentation for the generated code can be generated with Yard
  using a command like `yard doc -m markdown myclient.rb`.  The API
  documentation is decent and should help make clients much more
  accessible.  It's currently missing information about the payload
  format you need to specify when making requests, and also about the
  payload format you can expect in responses.

  Some examples:

    http://cl.ly/image/3B3Q3H472J2N
    http://cl.ly/image/0108282T2d3E
    http://cl.ly/image/46412o253v3Y

- A new `Heroics::LinkSchema.parameter_names` method correctly
  dereferences property definitions defined in link hrefs.  New
  `Parameter` and `ParameterChoice` (for `anyOf` and `oneOf` identity
  properties, primarily) are returned and used by the code generator
  to build function signatures and Yard-compatible docstrings.

- The existing `Heroics::LinkSchema.parameters` methods, used
  elsewhere, should be updated to use the correct property
  dereferencing logic.  I've intentionally left that out of scope in
  this branch.  It's needed to fix broken examples in the CLI and
  clean up some other details, but I think we can push those changes
  later when everything works, in a separate branch.  When those
  changes are in place we can also include request and response
  examples in the docstrings so that they're easily discoverable in
  generated API documentation.

In theory, we could generate a (backwards-compatible) `platform-api`
gem with what's here.  I've played with the generated code and it
seems to work, but I've not done extensive testing, so at this point
I'm waiting for reviews and more testing before going ahead and doing
that last step.

FYI @geemus @mmcgrana @sclasen