GrapeApiary

Auto generates an Apiary Blueprint from the docuementation that is created by your Grape API.

NOTE

This is an early implementation that makes some assumptions about your API (follows a standard REST pattern) that works with our implementation of Grape API's. There is a new an unreleased feature in Grape that allows for appending additional documentation. This project is dependent on this feature in order to create example JSON requests and responses.

Installation

Add this line to your application's Gemfile:

gem 'grape', github: 'intridea/grape' # see note above
gem 'grape-apiary'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-apiary

Usage

Add some metadata about your API and then execute the generate method on the GrapeApiary::Blueprint class.

Configuration

Configure details about your api in an initializers or similar:

GrapeApiary.config do |config|
  # your apiary.io host name
  config.host               = 'http://awesome-api.apiary.io'
  # the name of your api
  config.name               = 'Awesome API'
  # a description for your api
  config.description        = 'The awesome description'
  # the type to use for generated sample id's (`integer` or `uuid`)
  config.example_id_type    = :uuid
  # resources you do not want documented
  config.resource_exclusion = [:admin, :swagger_doc]
end

# request headers you want documented
GrapeApiary.config.request_headers = [
  { 'Accept-Charset' => 'utf-8' },
  { 'Connection'     => 'keep-alive' }
]

# response headers you want documented
GrapeApiary.config.response_headers = [
  { 'Content-Length' => '21685' },
  { 'Connection'     => 'keep-alive' }
]

Generation

# supply the class you'd like to document and generate your blueprint
GrapeApiary::Blueprint.new(AwesomeAPI).generate

TODO

Add a rake task to simplify generation
Add support for listing all of a resources attributes at the resource level as a markdown table
Handle ever changing sample id's (don't want git diff's after every generation)
Add option to change or remove the sample id field (eg. _id vs id)
What if someone does not use JSON?!?
Creat sample response for list endpoints (array)

Contributing

Fork it ( http://github.com//grape-apiary/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request