client-generator

[jkakar]

• 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 method, 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

[jkakar]

@sclasen If you have time and interest in taking this further I think
the next set of things to concentrate on would be:

• Generate a client for the Heroku Platform API and do some extensive
  testing.

• Generate a client for another API, such as Direwolf or Vault, and
  make sure things work as expected.

• Land this branch and then look at deleting LinkSchema.parameters
  and replacing all the bits that use it with the new (and correct)
  LinkSchema.parameter_details. In particular, the help
  documentation generated by the builtin CLI here:

  https://github.com/heroku/heroics/blob/master/lib/heroics/command.rb#L27-L50

  could be much better.

• Look at including example objects for request and response bodies in
  the docstrings in generated client code and make them render nicely
  in Yard API documentation.

All that said, I'm happy to pick these tasks up when I'm back from
Gophercon, so if this turns out to be hard to get into, or
uninteresting, please feel free to leave it to me.

[sclasen]

@jkakar I see that you re-mocked out the schema loading.

I was planning on actually taking the results of evaling the generated client and writing some integration tests with it, inside heroics. Is that what you had in mind wrt "Generate a client for the Heroku Platform API and do some extensive testing."?

Would need a real schema for that of course.

So if thats what you had in mind, where should integration tests go?

If not what did you have in mind?

[jkakar]

The test is using the sample schema to generate code and is evaling
that. The sample schema captures a number of different API
characteristics and is used by all the other tests. I used it to
avoid hitting the network to download a Heroku Platform API schema.
It means the test suite can continue to be run offline, which isn't a
big deal, but nice to have.

In terms of testing, I was going to load the generated client in a
console and play with it to make sure it works.