Skip to content
This repository has been archived by the owner. It is now read-only.
Allows for generating a Slate (https://github.com/tripit/slate) style for your Grape API
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Bump hotfix number [skip ci] Feb 27, 2015
spec Style guide related changes Feb 27, 2015
.gitignore Initial commit Feb 25, 2014
.rspec Initial commit Feb 25, 2014
.rubocop.yml Style guide related changes Feb 27, 2015
.travis.yml Initial commit Feb 25, 2014
Gemfile Don't rely on local gems! Feb 26, 2014
Guardfile Initial commit Feb 25, 2014
LICENSE.txt
README.md Fixes documentation related to #generate Jul 26, 2015
Rakefile Added a "Required" column indicating if the HTTP parameter listed is … Feb 27, 2015
grape-slate.gemspec Update grape-markdown gem Feb 27, 2014

README.md

GrapeSlate

Code Climate Build Status Coverage Status Dependency Status Gem Version

Auto generates an Slate Document 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-slate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-slate

Usage

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

Configuration

Configure details about your api in an initializers or similar:

GrapeSlate.config do |config|
  # 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]
  # whether or not examples should include a root element (default: false)
  config.include_root       = true
end

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

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

Generation

# supply the class you'd like to document and generate your blueprint
GrapeSlate::Document.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?!?
  • Create sample response for list endpoints (array)
  • Add support for writing the blueprint to disk
  • Add an option to include root in json

Contributing

  1. Fork it ( http://github.com/connexio-labs/grape-slate/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
You can’t perform that action at this time.