heroku/heroics — pull request #26 by jkakar (2014-04-23 06:25:11+00:00)
Title: 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