grape-markdown 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3dc94cf1475a3e3615cc3215cdf9e54eb6a02fa8
+  data.tar.gz: 7d5e62aa00c83c69d95bc20c9b0d592bd47ddc87
+SHA512:
+  metadata.gz: 855fcaf8917043fe5a6121a1722f6669a73d18bf3cb660ed8ca977f6f3b28b8534b27b1f6b4c600688e52a2c455c8fe34510e80ef54e7de7f4e88c45698bf999
+  data.tar.gz: 93694b04db560f1c38c99d1dc247602da9372092aab7501b71403eae875e2c57d80a59b2361a5c73660c867993f456f9edf68689f2ddad9797fd2c0ac6a218e0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format=progress

data/.rubocop.yml

@@ -0,0 +1,18 @@
+AllCops:
+  Excludes:
+    - Rakefile
+    - vendor/**
+    - bin/**
+
+Documentation:
+  # don't require classes to be documented
+  Enabled: false
+
+Encoding:
+  # no need to always specify encoding
+  Enabled: false
+
+LineLength:
+  # just one more character please
+  Max: 80
+

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.1.0
+  - 2.0.0
+  - 1.9.3
+  - jruby
+addons:
+  code_climate:
+    repo_token: 

data/Gemfile

@@ -0,0 +1,18 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in grape-markdown.gemspec
+gemspec
+
+gem 'grape', github: 'intridea/grape'
+
+group :development, :test do
+  gem 'coveralls', '~> 0.7'
+  gem 'rspec', '~> 2.14'
+  gem 'bundler', '~> 1.5'
+  gem 'rake', '~> 10.0'
+  gem 'rubocop', '~> 0.18'
+  gem 'pry', '~> 0.9'
+  gem 'guard', '~> 2.4'
+  gem 'guard-rspec', '~> 4.2'
+  gem 'guard-bundler', '~> 2.0'
+end

data/Guardfile

@@ -0,0 +1,12 @@
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec/" }
+end
+
+guard 'bundler' do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 John Allen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# GrapeMarkdown
+
+[![Code Climate](https://codeclimate.com/github/connexio-labs/grape-markdown.png)](https://codeclimate.com/github/connexio-labs/grape-markdown)
+[![Build Status](https://travis-ci.org/connexio-labs/grape-markdown.png?branch=master)](https://travis-ci.org/connexio-labs/grape-markdown)
+[![Coverage Status](https://coveralls.io/repos/connexio-labs/grape-markdown/badge.png)](https://coveralls.io/r/connexio-labs/grape-markdown)
+[![Dependency Status](https://gemnasium.com/connexio-labs/grape-markdown.png)](https://gemnasium.com/connexio-labs/grape-markdown)
+[![Gem Version](https://badge.fury.io/rb/grape-markdown.png)](http://badge.fury.io/rb/grape-markdown)
+
+Auto generates Markdown from the docuementation that is created by your [Grape](https://github.com/intridea/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. This project will generate a very simplistic Markdown document. It primarily adds some wrappers around Grape's documentation and enables other gems ([grape-apiary](https://github.com/connexio-labs/grape-apiary) and [grape-slate](https://github.com/connexio-labs/grape-slate)) to generate Markdown in specific formats.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'grape-markdown'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install grape-markdown
+
+## Usage
+
+Add some metadata about your API and then execute the `generate` method on the `GrapeMarkdown::Document` class.
+
+### Configuration
+
+Configure details about your api in an initializers or similar:
+
+```ruby
+GrapeMarkdown.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
+GrapeMarkdown.config.request_headers = [
+  { 'Accept-Charset' => 'utf-8' },
+  { 'Connection'     => 'keep-alive' }
+]
+
+# response headers you want documented
+GrapeMarkdown.config.response_headers = [
+  { 'Content-Length' => '21685' },
+  { 'Connection'     => 'keep-alive' }
+]
+```
+
+### Generation
+
+```ruby
+# supply the class you'd like to document and generate your blueprint
+GrapeMarkdown::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 markdown to disk
+* ~~Add an option to include root in json~~
+
+## Contributing
+
+1. Fork it ( http://github.com/connexio-labs/grape-markdown/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

data/Rakefile

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup :default, :test, :development
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+require 'rainbow/ext/string' unless String.respond_to?(:color)
+require 'rubocop/rake_task'
+Rubocop::RakeTask.new(:rubocop)
+
+task default: [:rubocop, :spec]
+
+task :console do
+  require 'pry'
+  require 'grape-markdown'
+  ARGV.clear
+  Pry.start
+end

data/grape-markdown.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'grape-markdown/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'grape-markdown'
+  spec.version       = GrapeMarkdown::VERSION
+  spec.authors       = ['John Allen']
+  spec.email         = ['john@threedogconsulting.com']
+  spec.summary       = %q{Allows for generating a Markdown document from you Grape API}
+  spec.description   = %q{Auto generates Markdown from the docuementation that is created by your Grape API}
+  spec.homepage      = 'https://github.com/connexio-labs/grape-markdown'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'grape', '~> 0.6'
+
+  spec.add_development_dependency 'coveralls', '~> 0.7'
+  spec.add_development_dependency 'rspec', '~> 2.14'
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop', '~> 0.18'
+  spec.add_development_dependency 'pry', '~> 0.9'
+  spec.add_development_dependency 'guard', '~> 2.4'
+  spec.add_development_dependency 'guard-rspec', '~> 4.2'
+  spec.add_development_dependency 'guard-bundler', '~> 2.0'
+end

data/lib/grape/markdown.rb

@@ -0,0 +1 @@
+require 'grape-markdown'

data/lib/grape-markdown/config.rb

@@ -0,0 +1,62 @@
+module GrapeMarkdown
+  class Config
+    SETTINGS = [
+      :name,
+      :description,
+      :request_headers,
+      :response_headers,
+      :example_id_type,
+      :resource_exclusion,
+      :include_root
+    ]
+
+    class << self
+      attr_accessor(*SETTINGS)
+
+      def request_headers
+        @request_headers ||= []
+      end
+
+      def response_headers
+        @response_headers ||= []
+      end
+
+      def resource_exclusion
+        @resource_exclusion ||= []
+      end
+
+      def include_root
+        @include_root ||= false
+      end
+
+      def supported_id_types
+        [:integer, :uuid, :bson]
+      end
+
+      def example_id_type=(value)
+        fail UnsupportedIDType unless supported_id_types.include?(value)
+
+        if value.to_sym == :bson && !Object.const_defined?('BSON')
+          fail BSONNotDefinied
+        end
+
+        @example_id_type = value
+      end
+
+      def example_id_type
+        @example_id_type ||= :integer
+      end
+
+      def generate_id
+        case example_id_type
+        when :integer
+          SecureRandom.random_number(1000)
+        when :uuid
+          SecureRandom.uuid
+        when :bson
+          BSON::ObjectId.new.to_s
+        end
+      end
+    end
+  end
+end

data/lib/grape-markdown/document.rb

@@ -0,0 +1,76 @@
+module GrapeMarkdown
+  class Document
+    attr_reader :api_class, :document_template, :properties_template
+
+    delegate(*GrapeMarkdown::Config::SETTINGS, to: 'GrapeMarkdown::Config')
+
+    def initialize(api_class)
+      @api_class           = api_class
+      @document_template   = template_for(:document)
+      @properties_template = template_for(:properties)
+    end
+
+    def generate
+      ERB.new(document_template, nil, '-').result(binding)
+    end
+
+    def write
+      fail 'Not yet supported'
+    end
+
+    def routes
+      @routes ||= api_class.routes.map do |route|
+        GrapeMarkdown::Route.new(route)
+      end
+    end
+
+    def resources
+      @resources ||= begin
+        grouped_routes = routes.group_by(&:route_name).reject do |name, routes|
+          resource_exclusion.include?(name.to_sym)
+        end
+
+        grouped_routes.map { |name, routes| Resource.new(name, routes) }
+      end
+    end
+
+    def properties_table(resource)
+      ERB.new(properties_template, nil, '-').result(resource.resource_binding)
+    end
+
+    def formatted_request_headers
+      formatted_headers(GrapeMarkdown::Config.request_headers)
+    end
+
+    def formatted_response_headers
+      formatted_headers(GrapeMarkdown::Config.response_headers)
+    end
+
+    def show_request_sample?(route)
+      %w(PUT POST).include?(route.route_method)
+    end
+
+    private
+
+    def template_for(name)
+      directory = File.dirname(File.expand_path(__FILE__))
+      path = File.join(directory, "./templates/#{name}.md.erb")
+
+      File.read(path)
+    end
+
+    def formatted_headers(headers)
+      return '' unless headers.present?
+
+      spacer  = "\n" + (' ' * 12)
+
+      strings = headers.map do |header|
+        key, value = *header.first
+
+        "#{key}: #{value}"
+      end
+
+      "    + Headers\n" + spacer + strings.join(spacer)
+    end
+  end
+end

data/lib/grape-markdown/parameter.rb

@@ -0,0 +1,45 @@
+module GrapeMarkdown
+  class Parameter
+    attr_reader :route, :full_name, :name, :settings
+
+    delegate :route_model, :route_namespace, to: :route
+    delegate :requirement, :type, :documentation, :desc, to: :settings
+    delegate :example, to: :documentation, allow_nil: true
+
+    def initialize(route, name, options)
+      @full_name = name
+      @name      = name
+      @name      = name.scan(/\[(.*)\]/).flatten.first if name.include?('[')
+      @route     = route
+      @settings  = parse_options(options)
+    end
+
+    def description
+      "#{name} (#{requirement}, #{type}, `#{example}`) ... #{desc}"
+    end
+
+    private
+
+    def parse_options(options)
+      options = default_options(options) if options.blank?
+
+      options[:requirement] = options[:required] ? 'required' : 'optional'
+
+      Hashie::Mash.new(options)
+    end
+
+    def default_options(options)
+      model = name.include?('_id') ? name.gsub('_id', '') : route.route_model
+
+      {
+        required:       true,
+        requirement:    'required',
+        type:           'uuid',
+        desc:           "the `id` of the `#{model}`",
+        documentation:  {
+          example:      GrapeMarkdown::Config.generate_id
+        }
+      }
+    end
+  end
+end

data/lib/grape-markdown/resource.rb

@@ -0,0 +1,63 @@
+module GrapeMarkdown
+  class Resource
+    attr_reader :key, :name, :routes, :sample_generator
+
+    def initialize(key, routes)
+      @key              = key
+      @name             = key.humanize
+      @routes           = routes
+      @sample_generator = SampleGenerator.new(self)
+    end
+
+    def title
+      @title ||= name.titleize
+    end
+
+    def namespaced
+      @namespaced ||= routes.group_by(&:route_namespace).map do |_, routes|
+        Resource.new(name, routes)
+      end
+    end
+
+    def paths
+      @paths ||= routes.group_by(&:route_path_without_format).map do |n, routes|
+        Resource.new(name, routes)
+      end
+    end
+
+    def header
+      # TODO: ???
+      route = routes.first
+
+      "#{title} #{route.route_type} [#{route.route_path_without_format}]"
+    end
+
+    def sample_request
+      sample_generator.request
+    end
+
+    def sample_response(route)
+      sample_generator.response(route.list?)
+    end
+
+    def unique_params
+      # TODO: this is a hack, assuming that the resource has a POST or PUT
+      # route that defines all of the parameters that would define the resource
+      methods = %w(POST PUT)
+
+      potential = routes.select do |route|
+        methods.include?(route.route_method) && route.route_params.present?
+      end
+
+      if potential.present?
+        potential.first.route_params
+      else
+        []
+      end
+    end
+
+    def resource_binding
+      binding
+    end
+  end
+end

data/lib/grape-markdown/route.rb

@@ -0,0 +1,54 @@
+module GrapeMarkdown
+  class Route < SimpleDelegator
+    # would like to rely on SimpleDelegator but Grape::Route uses
+    # method_missing for these methods :'(
+    delegate :route_namespace, :route_path, :route_method, to: '__getobj__'
+
+    def route_params
+      @route_params ||= __getobj__.route_params.sort.map do |param|
+        Parameter.new(self, *param)
+      end
+    end
+
+    def route_name
+      route_namespace.split('/').last ||
+        route_path.match('\/(\w*?)[\.\/\(]').captures.first
+    end
+
+    def route_description
+      "#{__getobj__.route_description} [#{route_method.upcase}]"
+    end
+
+    def route_path_without_format
+      route_path.gsub(/\((.*?)\)/, '')
+    end
+
+    def route_model
+      route_namespace.split('/').last.singularize
+    end
+
+    def route_type
+      list? ? 'collection' : 'single'
+    end
+
+    def request_description
+      "+ Request #{'(application/json)' if request_body?}"
+    end
+
+    def response_description
+      code = route_method == 'POST' ? 201 : 200
+
+      "+ Response #{code} (application/json)"
+    end
+
+    def list?
+      %w(GET POST).include?(route_method) && !route_path.include?(':id')
+    end
+
+    private
+
+    def request_body?
+      !%w(GET DELETE).include?(route_method)
+    end
+  end
+end

data/lib/grape-markdown/sample_generator.rb

@@ -0,0 +1,55 @@
+module GrapeMarkdown
+  class SampleGenerator
+    attr_reader :resource, :root
+
+    delegate :unique_params, to: :resource
+
+    def initialize(resource)
+      @resource = resource
+      @root     = resource.key.singularize
+    end
+
+    def sample(id = false)
+      array = resource.unique_params.map do |param|
+        next if param.name == root
+
+        [param.name, param.example]
+      end
+
+      hash = Hash[array.compact]
+
+      hash = hash.reverse_merge(id: Config.generate_id) if id
+      hash = { root => hash } if Config.include_root
+
+      hash
+    end
+
+    def request
+      hash = sample
+
+      return unless hash.present?
+
+      # format json spaces for blueprint markdown
+      JSON.pretty_generate(hash)
+        .gsub('{', (' ' * 14) + '{')
+        .gsub('}', (' ' * 14) + '}')
+        .gsub(/\ {2}\"/, (' ' * 16) + '"')
+    end
+
+    def response(list = false)
+      hash = sample(true)
+
+      return unless hash.present?
+
+      hash = [hash] if list
+
+      # format json spaces for blueprint markdown
+      JSON.pretty_generate(hash)
+        .gsub('[', (' ' * 12) + '[')
+        .gsub(']', (' ' * 12) + ']')
+        .gsub('{', (' ' * 14) + '{')
+        .gsub('}', (' ' * 14) + '}')
+        .gsub(/\ {2}\"/, (' ' * 16) + '"')
+    end
+  end
+end

data/lib/grape-markdown/templates/document.md.erb

@@ -0,0 +1,15 @@
+# <%= name %>
+
+<%= description %>
+
+<% resources.each do |resource| %>
+# <%= resource.title %>
+<%= properties_table(resource) %>
+  <% resource.namespaced.each do |grouped_resource| %>
+    <% grouped_resource.paths.each do |resource_by_path| %>
+      <% resource_by_path.routes.each do |route| %>
+## <%= route.route_description %>
+      <% end %>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/grape-markdown/templates/properties.md.erb

@@ -0,0 +1,7 @@
+Properties
+
+| Name | Type | Description |
+|:-----|:-----|:------------|
+<% unique_params.each do |param| -%>
+| <%= param.full_name %> |  <%= param.type %> | <%= param.desc %> |
+<% end -%>

data/lib/grape-markdown/version.rb

@@ -0,0 +1,3 @@
+module GrapeMarkdown
+  VERSION = '0.0.1'
+end

data/lib/grape-markdown.rb

@@ -0,0 +1,27 @@
+require 'grape'
+
+module GrapeMarkdown
+  autoload :Version,         'grape-markdown/version'
+  autoload :Config,          'grape-markdown/config'
+  autoload :Parameter,       'grape-markdown/parameter'
+  autoload :SampleGenerator, 'grape-markdown/sample_generator'
+  autoload :Route,           'grape-markdown/route'
+  autoload :Resource,        'grape-markdown/resource'
+  autoload :Document,        'grape-markdown/document'
+
+  def self.config
+    block_given? ? yield(Config) : Config
+  end
+end
+
+class UnsupportedIDType < StandardError
+  def message
+    'Unsupported id type, supported types are [integer, uuid, bson]'
+  end
+end
+
+class BSONNotDefinied < StandardError
+  def message
+    'BSON type id requested but bson library is not present'
+  end
+end

data/spec/grape-markdown/config_spec.rb

@@ -0,0 +1,91 @@
+require 'spec_helper'
+
+describe GrapeMarkdown::Config do
+  include_context 'configuration'
+
+  subject { GrapeMarkdown::Config }
+
+  it 'allows for name to be set' do
+    subject.name = name
+
+    expect(subject.name).to eq(name)
+  end
+
+  it 'allows for description to be set' do
+    subject.description = description
+
+    expect(subject.description).to eq(description)
+  end
+
+  context '.include_root' do
+    it 'defaults to false' do
+      expect(subject.include_root).to be(false)
+    end
+
+    it 'allows for inclusion of the root to be set' do
+      subject.include_root = true
+
+      expect(subject.include_root).to eq(true)
+    end
+  end
+
+  context 'headers' do
+    [:request_headers, :response_headers].each do |type|
+      context type do
+        it 'is an array' do
+          expect(subject.send(type)).to be_a(Array)
+        end
+
+        it 'allows for request headers to be set in bulk' do
+          headers = send(type)
+
+          subject.send("#{type}=", headers)
+
+          expect(subject.send(type)).to eq(headers)
+        end
+
+        it 'allows for request headers to be set individually' do
+          header = { Host: 'api.connexiolabs-qa.com' }
+
+          expect do
+            subject.send(type) << header
+          end.to change { subject.send(type).length }.by(1)
+        end
+      end
+    end
+  end
+
+  context 'sample id generation' do
+    it 'allows for setting the type for id generation' do
+      subject.example_id_type = :uuid
+
+      expect(subject.example_id_type).to eq(:uuid)
+    end
+
+    it 'guards against unsupported types' do
+      expect do
+        subject.example_id_type = :foo
+      end.to raise_error(UnsupportedIDType)
+    end
+
+    it 'checks for the bson library if requested' do
+      expect { subject.example_id_type = :bson }.to raise_error(BSONNotDefinied)
+    end
+
+    it 'generates a valid uuid' do
+      test = /[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}/i
+
+      subject.example_id_type = :uuid
+
+      expect(subject.generate_id).to match(test)
+    end
+
+    it 'generates a valid integer' do
+      test = /^[0-9]{1,10}$/
+
+      subject.example_id_type = :integer
+
+      expect(subject.generate_id.to_s).to match(test)
+    end
+  end
+end

data/spec/grape-markdown/document_spec.rb

@@ -0,0 +1,73 @@
+require 'spec_helper'
+
+describe GrapeMarkdown::Document do
+  include_context 'configuration'
+
+  before do
+    GrapeMarkdown.config do |config|
+      config.name               = name
+      config.description        = description
+      config.resource_exclusion = [:admin]
+    end
+
+    GrapeMarkdown.config.request_headers = [
+      { 'Accept-Charset' => 'utf-8' },
+      { 'Connection'     => 'keep-alive' }
+    ]
+
+    GrapeMarkdown.config.response_headers = [
+      { 'Content-Length' => '21685' },
+      { 'Connection'     => 'keep-alive' }
+    ]
+  end
+
+  subject { GrapeMarkdown::Document.new(SampleApi) }
+
+  context '#generate' do
+    let(:klass) { SampleApi }
+
+    subject { GrapeMarkdown::Document.new(klass).generate }
+
+    it 'creates a header from configuration' do
+      expect(subject).to include("# #{name}")
+    end
+
+    it 'adds the description' do
+      expect(subject).to include(description)
+    end
+
+    it 'includes properties for the resources' do
+      expect(subject).to include('Properties')
+      `clear`
+      puts subject
+    end
+  end
+
+  it 'exposes configuration settings' do
+    GrapeMarkdown::Config::SETTINGS.each do |setting|
+      expect(subject.send(setting)).to eq(GrapeMarkdown.config.send(setting))
+    end
+  end
+
+  it 'exposes the raw routes of the given api' do
+    expect(subject.routes).to eq(SampleApi.routes)
+  end
+
+  context '#resources' do
+    let(:unique_routes) { subject.routes.map(&:route_name).uniq }
+
+    let(:included_routes) do
+      unique_routes.reject do |name|
+        GrapeMarkdown.config.resource_exclusion.include?(name.to_sym)
+      end
+    end
+
+    it 'aggregates routes into resources' do
+      expect(subject.resources.first).to be_a(GrapeMarkdown::Resource)
+    end
+
+    it 'excluded resources based on configuration' do
+      expect(subject.resources.map(&:key)).to eq(included_routes)
+    end
+  end
+end

data/spec/grape-markdown/resource_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe GrapeMarkdown::Resource do
+  include_context 'configuration'
+
+  subject { GrapeMarkdown::Resource.new('foo', []) }
+
+  context 'sample' do
+    it 'request generation is delegated to a generator' do
+      expect(subject.sample_generator).to receive(:request)
+
+      subject.sample_request
+    end
+
+    it 'response generation is delegated to a generator' do
+      expect(subject.sample_generator).to receive(:response)
+
+      subject.sample_response(GrapeMarkdown::Route.new(Grape::Route.new))
+    end
+  end
+end

data/spec/grape-markdown/route_spec.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+
+describe GrapeMarkdown::Route do
+  include_context 'configuration'
+
+  let(:routes) { GrapeMarkdown::Document.new(SampleApi).routes }
+
+  subject { routes.first }
+
+  it 'adds a name helper to routes' do
+    expect(subject.route_name).to eq('widgets')
+  end
+
+  it 'adds a path helper without format' do
+    expect(subject.route_path_without_format).to eq('/widgets')
+  end
+
+  it 'adds a type helper' do
+    expect(subject.route_type).to eq('collection')
+  end
+end

data/spec/grape-markdown/sample_generator_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe GrapeMarkdown::SampleGenerator do
+  include_context 'configuration'
+
+  before do
+    GrapeMarkdown.config do |config|
+      config.name               = name
+      config.description        = description
+      config.include_root       = false
+    end
+  end
+
+  let(:blueprint) { GrapeMarkdown::Document.new(SampleApi) }
+  let(:resource)  { blueprint.resources.first }
+
+  subject { GrapeMarkdown::SampleGenerator.new(resource) }
+
+  it 'creates a sample hash from a resource' do
+    expect(subject.sample).to be_a(Hash)
+  end
+
+  context '#request' do
+    it 'creates a sample request in JSON form' do
+      expect { JSON.parse(subject.request) }.to_not raise_error
+    end
+  end
+
+  context '#response' do
+    it 'creates a sample response in JSON form' do
+      expect { JSON.parse(subject.response) }.to_not raise_error
+    end
+
+    it 'includes a sample id' do
+      expect(JSON.parse(subject.response)['id']).to_not be(nil)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'support'))
+
+require 'grape/markdown'
+
+require 'rubygems'
+require 'bundler'
+Bundler.setup :default, :test
+
+require 'coveralls'
+Coveralls.wear!
+
+require 'rspec'
+require 'pry'
+
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }

data/spec/support/config_context.rb

@@ -0,0 +1,13 @@
+shared_context 'configuration' do
+  let(:name)               { 'some api v1' }
+  let(:description)        { 'some blueprint description' }
+  let(:resource_exclusion) { [:admin, :swagger_docs] }
+
+  let(:request_headers) do
+    [{ 'Accept-Charset' => 'utf-8' }]
+  end
+
+  let(:response_headers) do
+    [{ 'Connection'     => 'keep-alive' }]
+  end
+end

data/spec/support/sample_api.rb

@@ -0,0 +1,38 @@
+class SampleApi < Grape::API
+  resource 'widgets' do
+    desc 'widgets list'
+    get  '/' do
+    end
+
+    desc 'individual widget'
+    get ':id' do
+    end
+
+    desc 'create a widget'
+    params do
+      requires :name,
+               type: 'string',
+               desc: 'the widgets name',
+               documentation: { example: 'super widget' }
+      optional :description,
+               type: 'string',
+               desc: 'the widgets name',
+               documentation: { example: 'the best widget ever made' }
+    end
+    post '/' do
+    end
+
+    desc 'update a widget'
+    params do
+      optional :name, type: 'string', desc: 'the widgets name'
+      optional :description, type: 'string', desc: 'the widgets name'
+    end
+    put  ':id' do
+    end
+  end
+
+  resource 'admin' do
+    get '/' do
+    end
+  end
+end

metadata

@@ -0,0 +1,223 @@
+--- !ruby/object:Gem::Specification
+name: grape-markdown
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- John Allen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: grape
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: guard-bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Auto generates Markdown from the docuementation that is created by your
+  Grape API
+email:
+- john@threedogconsulting.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- Guardfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- grape-markdown.gemspec
+- lib/grape-markdown.rb
+- lib/grape-markdown/config.rb
+- lib/grape-markdown/document.rb
+- lib/grape-markdown/parameter.rb
+- lib/grape-markdown/resource.rb
+- lib/grape-markdown/route.rb
+- lib/grape-markdown/sample_generator.rb
+- lib/grape-markdown/templates/document.md.erb
+- lib/grape-markdown/templates/properties.md.erb
+- lib/grape-markdown/version.rb
+- lib/grape/markdown.rb
+- spec/grape-markdown/config_spec.rb
+- spec/grape-markdown/document_spec.rb
+- spec/grape-markdown/resource_spec.rb
+- spec/grape-markdown/route_spec.rb
+- spec/grape-markdown/sample_generator_spec.rb
+- spec/spec_helper.rb
+- spec/support/config_context.rb
+- spec/support/sample_api.rb
+homepage: https://github.com/connexio-labs/grape-markdown
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Allows for generating a Markdown document from you Grape API
+test_files:
+- spec/grape-markdown/config_spec.rb
+- spec/grape-markdown/document_spec.rb
+- spec/grape-markdown/resource_spec.rb
+- spec/grape-markdown/route_spec.rb
+- spec/grape-markdown/sample_generator_spec.rb
+- spec/spec_helper.rb
+- spec/support/config_context.rb
+- spec/support/sample_api.rb
+has_rdoc: