grape-swagger 0.7.2 → 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6a1bf3c5bf4c84bdda47522ddc8148c78c538995
+  data.tar.gz: 04f9c3468140334518a3051593c5ff94da824a0a
+SHA512:
+  metadata.gz: 302ac60608a12fcbb40ea2988ad73a4459e469605058992aa379f6c6d5d043855560db1d57de531a280e05e054cab6d962cbc6847f405166fec25aadd5d2deb7
+  data.tar.gz: 9b1a01f0aac40776531b393465e24baa14b873824ada7171df0e546711bb92d143804d44339b8ae27fd1313afcd74e46aa50fe92ce059807c55d86b87dcff219

data/.gitignore

@@ -0,0 +1,33 @@
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkg
+
+# rails stuff
+log/*.log
+test/dummy/db/*.sqlite3
+test/dummy/log/*.log
+test/dummy/tmp/
+test/dummy/.sass-cache
+Gemfile.lock
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+.DS_Store
+.project

data/.rubocop.yml

@@ -0,0 +1,36 @@
+AllCops:
+  Excludes:
+    - vendor/**/*
+
+LineLength:
+  Enabled: false
+
+MethodLength:
+  Enabled: false
+
+ClassLength:
+  Enabled: false
+
+Documentation:
+  # don't require classes to be documented
+  Enabled: false
+
+Encoding:
+  # no need to always specify encoding
+  Enabled: false
+
+FileName:
+  # allow grape-swagger.rb
+  Enabled: false
+
+PredicateName:
+  Enabled: false
+
+DoubleNegation:
+  Enabled: false
+
+CyclomaticComplexity:
+  Enabled: false
+
+ClassVars:
+  Enabled: false

data/.ruby-gemset

@@ -0,0 +1 @@
+grape-swagger

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.2

data/.travis.yml

@@ -2,4 +2,7 @@ rvm:
   - jruby-19mode
   - 1.9.3
   - 2.0.0
+  - 2.1.2
+  - rbx-2.2.10
+
 

data/CHANGELOG.md

@@ -0,0 +1,90 @@
+### 0.8.0 (August 30, 2014)
+
+#### Features
+
+* [#139](https://github.com/tim-vandecasteele/grape-swagger/pull/139): Added support for `Rack::Multipart::UploadedFile` parameters - [@timgluz](https://github.com/timgluz).
+* [#136](https://github.com/tim-vandecasteele/grape-swagger/pull/136), [#94](https://github.com/tim-vandecasteele/grape-swagger/pull/94): Recurse combination of namespaces when using mounted apps - [@renier](https://github.com/renier).
+* [#100](https://github.com/tim-vandecasteele/grape-swagger/pull/100): Added ability to specify a nickname for an endpoint - [@lhorne](https://github.com/lhorne).
+* [#94](https://github.com/tim-vandecasteele/grape-swagger/pull/94): Added support for namespace descriptions - [@renier](https://github.com/renier).
+* [#110](https://github.com/tim-vandecasteele/grape-swagger/pull/110), [#111](https://github.com/tim-vandecasteele/grape-swagger/pull/111) - Added `responseModel` support - [@bagilevi](https://github.com/bagilevi).
+* [#114](https://github.com/tim-vandecasteele/grape-swagger/pull/114): Added support for generating nested models from composed Grape Entities - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#124](https://github.com/tim-vandecasteele/grape-swagger/pull/124): Added ability to change the description and parameters of the API endpoints generated by grape-swagger - [@dblock](https://github.com/dblock).
+* [#128](https://github.com/tim-vandecasteele/grape-swagger/pull/128): Combine global models and endpoint entities - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#132](https://github.com/tim-vandecasteele/grape-swagger/pull/132): Addes support for enum values in entity documentation and form parameters - [@Antek-drzewiecki](https://github.com/Antek-drzewiecki).
+* [#142](https://github.com/tim-vandecasteele/grape-swagger/pull/142), [#143](https://github.com/tim-vandecasteele/grape-swagger/pull/143): Added support for kramdown, redcarpet and custom formatters - [@Antek-drzewiecki](https://github.com/Antek-drzewiecki).
+
+#### Fixes
+
+* [#105](https://github.com/tim-vandecasteele/grape-swagger/pull/105): Fixed compatibility with Swagger-UI - [@CraigCottingham](https://github.com/CraigCottingham).
+* [#87](https://github.com/tim-vandecasteele/grape-swagger/pull/87): Fixed mapping of `default` to `defaultValue` - [@m-o-e](https://github.com/m-o-e).
+* [#127](https://github.com/tim-vandecasteele/grape-swagger/pull/127): Fixed `undefined method 'reject' for nil:NilClass` error for an invalid route, now returning 404 Not Found - [@dblock](https://github.com/dblock).
+* [#135](https://github.com/tim-vandecasteele/grape-swagger/pull/135): Fixed model inclusion in models with aliased references - [@cdarne](https://github.com/cdarne).
+
+#### Dev
+
+* [#126](https://github.com/tim-vandecasteele/grape-swagger/pull/126): Rewritten demo in the `test` folder with CORS enabled - [@dblock](https://github.com/dblock).
+* Rewritten .gemspec and removed Jeweler - [@dblock](https://github.com/dblock).
+* Added `GrapeSwagger::VERSION` - [@dblock](https://github.com/dblock).
+* Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
+
+### 0.7.2 (February 6, 2014)
+
+* [#84](https://github.com/tim-vandecasteele/grape-swagger/pull/84): Markdown is now Github Flavored Markdown - [@jeromegn](https://github.com/jeromegn).
+* [#83](https://github.com/tim-vandecasteele/grape-swagger/pull/83): Improved support for nested Entity types - [@jeromegn](https://github.com/jeromegn).
+* [#79](https://github.com/tim-vandecasteele/grape-swagger/pull/79): Added `dataType` to the `params` output - [@Phobos98](https://github.com/Phobos98).
+* [#75](https://github.com/tim-vandecasteele/grape-swagger/pull/75), [#82](https://github.com/tim-vandecasteele/grape-swagger/pull/82): Added Swagger 1.2 support - [@joelvh](https://github.com/joelvh), [@jeromegn](https://github.com/jeromegn).
+* [#73](https://github.com/tim-vandecasteele/grape-swagger/pull/73): Added the ability to add additional API `info` - [@mattbeedle](https://github.com/mattbeedle).
+* [#69](https://github.com/tim-vandecasteele/grape-swagger/pull/69): Make relative `base_path` values absolute - [@dm1try](https://github.com/dm1try).
+* [#66](https://github.com/tim-vandecasteele/grape-swagger/pull/66): Fixed documentation generated for paths that don't match the base URL pattern - [@swistaczek](https://github.com/swistaczek).
+* [#63](https://github.com/tim-vandecasteele/grape-swagger/pull/63): Added support for hiding endpoints from the documentation - [@arturoherrero](https://github.com/arturoherrero).
+* [#62](https://github.com/tim-vandecasteele/grape-swagger/pull/62): Fixed handling of URLs with the `-` character - [@dadario](https://github.com/dadario).
+* [#57](https://github.com/tim-vandecasteele/grape-swagger/pull/57): Fixed documenting of multiple API versions - [@Drakula2k](https://github.com/Drakula2k).
+* [#58](https://github.com/tim-vandecasteele/grape-swagger/pull/58): Fixed resource groupings for prefixed APIs - [@aew](https://github.com/aew).
+* [#56](https://github.com/tim-vandecasteele/grape-swagger/pull/56): Fixed `hide_documentation_path` on prefixed APIs - [@spier](https://github.com/spier).
+* [#54](https://github.com/tim-vandecasteele/grape-swagger/pull/54): Adding support for generating swagger `responseClass` and models from Grape Entities - [@calebwoods](https://github.com/calebwoods).
+* [#46](https://github.com/tim-vandecasteele/grape-swagger/pull/46): Fixed translating parameter `type` to String, enables using Mongoid fields as parameter definitions - [@dblock](https://github.com/dblock).
+
+### 0.6.0 (June 19, 2013)
+
+* Added Rails 4 support - [@jrhe](https://github.com/jrhe).
+* Fix: document APIs at root level - [@dblock](https://github.com/dblock).
+* Added support for procs in basepath - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Support both `:desc` and `:description` when describing parameters - [@dblock](https://github.com/dblock).
+* Fix: allow parameters such as `name[]` - [@dblock](https://github.com/dblock).
+
+### 0.5.0 (March 28, 2013)
+
+* Added Grape 0.5.0 support - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+
+### 0.4.0 (March 28, 2013)
+
+* Support https - [@cutalion](https://github.com/cutalion).
+
+### 0.3.0 (October 19, 2012)
+
+* Added version support - [@agileanimal](https://github.com/agileanimal), [@fknappe](https://github.com/fknappe).
+* Added support for nested parameters - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added basic support for specifying parameters that need to be passed in the header - [@agileanimal](https://github.com/agileanimal).
+* Add possibility to hide the documentation paths in the generated swagger documentation - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+
+### 0.2.1 (August 17, 2012)
+
+* Added support for markdown in notes field - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Fix: compatibility with Rails - [@qwert666](https://github.com/qwert666).
+* Fix: swagger UI history - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+
+### 0.2.0 (July 27, 2012)
+
+* Use resource as root for swagger - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added support for file uploads, and proper `paramType` - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Added tests - [@nathanvda](https://github.com/nathanvda).
+
+### 0.1.0 (July 19, 2012)
+
+* Added some configurability to the generated documentation - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Adapted to rails plugin structure - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* Allowed cross origin, so swagger can be used from official site - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+
+### 0.0.0 (July 19, 2012)
+
+* Initial public release - [@tim-vandecasteele](https://github.com/tim-vandecasteele).

data/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to Grape-Swagger
+
+This project is work of [many contributors](https://github.com/tim-vandecasteele/grape-swagger/graphs/contributors).
+You're encouraged to submit [pull requests](https://github.com/tim-vandecasteele/grape-swagger/pulls),
+[propose features and discuss issues](https://github.com/tim-vandecasteele/grape-swagger/issues).
+When in doubt, ask a question in the [Grape Google Group](http://groups.google.com/group/ruby-grape).
+
+In the examples below, substitute your Github username for `contributor` in URLs.
+
+## Fork the Project
+
+Fork the [project on Github](https://github.com/tim-vandecasteele/grape-swagger) and check out your copy.
+
+```
+git clone https://github.com/contributor/grape-swagger.git
+cd grape-swagger
+git remote add upstream https://github.com/tim-vandecasteele/grape-swagger.git
+```
+
+## Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+## Bundle Install and Test
+
+Ensure that you can build the project and run tests.
+
+```
+bundle install
+bundle exec rake
+```
+
+## Write Tests
+
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build.
+Add to [spec](spec).
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+## Write Code
+
+Implement your feature or bug fix.
+
+Ruby style is enforced with [Rubocop](https://github.com/bbatsov/rubocop).
+Run `bundle exec rubocop` and fix any style issues highlighted.
+
+Make sure that `bundle exec rake` completes without errors.
+
+## Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+## Update Changelog
+
+Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*.
+Make it look like every other line, including your name and link to your Github account.
+
+## Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what changed and why.
+
+```
+git add ...
+git commit
+```
+
+## Push
+
+```
+git push origin my-feature-branch
+```
+
+## Make a Pull Request
+
+Go to https://github.com/contributor/grape and select your feature branch.
+Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+## Rebase
+
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+## Update CHANGELOG Again
+
+Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
+
+```
+* [#123](https://github.com/tim-vandecasteele/grape-swagger/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
+```
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+## Check on Your Pull Request
+
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+## Be Patient
+
+It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
+
+## Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.

data/Gemfile

@@ -1,23 +1,3 @@
 source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
 
-gem 'grape', '>= 0.2.0'
-gem 'grape-entity', '>= 0.3.0'
-gem 'kramdown', '>= 1.3.1'
-
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
-group :development do
-  gem "shoulda", ">= 0"
-  gem "rdoc", "~> 3.12"
-  gem "bundler", "> 1.0.0"
-  gem "jeweler", "~> 1.8.4"
-
-  gem "pry"
-
-  gem "rack-test"
-
-  gem "rspec"
-end
+gemspec

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Tim Vandecasteele
+Copyright (c) 2012-2014 Tim Vandecasteele and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,397 @@
+# grape-swagger
+
+[![Build Status](https://travis-ci.org/tim-vandecasteele/grape-swagger.svg?branch=master)](https://travis-ci.org/tim-vandecasteele/grape-swagger)
+
+## What is grape-swagger?
+
+The grape-swagger gem provides an autogenerated documentation for your [Grape](https://github.com/intridea/grape) API. The generated documentation is Swagger-compliant, meaning it can easily be discovered in [Swagger UI](https://github.com/wordnik/swagger-ui). You should be able to point [the petstore demo](http://petstore.swagger.wordnik.com) to your API.
+
+![Demo Screenshot](test/splines.png)
+
+## Related Projects
+
+* [Grape](https://github.com/intridea/grape)
+* [Swagger UI](https://github.com/wordnik/swagger-ui)
+
+## Installation
+
+Add to your Gemfile:
+
+```gem 'grape-swagger'```
+
+## Upgrade
+
+Please see [UPGRADING](UPGRADING.md) when upgrading from a previous version.
+
+## Usage
+
+Mount all your different APIs (with ```Grape::API``` superclass) on a root node. In the root class definition, include ```add_swagger_documentation```, this sets up the system and registers the documentation on '/swagger_doc.json'. See [test/api.rb](test/api.rb) for a simple demo.
+
+
+``` ruby
+require 'grape-swagger'
+
+module API
+  class Root < Grape::API
+    mount API::Cats
+    mount API::Dogs
+    mount API::Pirates
+    add_swagger_documentation
+  end
+end
+```
+
+To explore your API, either download [Swagger UI](https://github.com/wordnik/swagger-ui) and set it up yourself or go to the [online swagger demo](http://petstore.swagger.wordnik.com/) and enter your localhost url documentation root in the url field (probably something in the line of http://localhost:3000/swagger_doc.json).
+
+### CORS
+
+If you use the online demo, make sure your API supports foreign requests by enabling CORS in Grape, otherwise you'll see the API description, but requests on the API won't return. Use [rack-cors](https://github.com/cyu/rack-cors) to enable CORS.
+
+```` ruby
+require 'rack/cors'
+use Rack::Cors do
+  allow do
+    origins '*'
+    resource '*', headers: :any, methods: [ :get, :post, :put, :delete, :options ]
+  end
+end
+```
+
+Alternatively you can set CORS headers in a Grape `before` block.
+
+``` ruby
+before do
+  header['Access-Control-Allow-Origin'] = '*'
+  header['Access-Control-Request-Method'] = '*'
+end
+````
+
+## Configure
+
+You can pass a hash with optional configuration settings to ```add_swagger_documentation```.
+
+#### target_class
+
+The API class to document, default `self`.
+
+#### mount_path
+
+The path where the API documentation is loaded, default is `/swagger_doc`.
+
+#### class_name
+
+API class name.
+
+#### markdown
+
+Allow markdown in `notes`, default is `nil`. (disabled) See below for details.
+
+#### hide_format
+
+Don't add `.(format)` to the end of URLs, default is `false`.
+
+#### api_version
+
+Version of the API that's being exposed.
+
+#### base_path
+
+Base path of the API that's being exposed. This configuration parameter accepts a `proc` to evaluate `base_path`, useful when you need to use request attributes to determine its value.
+
+#### authorizations
+
+This value is added to the `authorizations` key in the JSON documentation.
+
+#### root_base_path
+
+Add `basePath` key to the JSON documentation, default is `true`.
+
+#### models
+
+A list of entities to document. Combine with the [grape-entity](https://github.com/intridea/grape-entity) gem. See below for details.
+
+#### hide_documentation_path
+
+Don't show the `/swagger_doc` path in the generated swagger documentation.
+
+#### format
+
+Documentation response format, default is `:json`.
+
+#### info
+
+A hash merged into the `info` key of the JSON documentation. This may contain:
+
+* `:title`: The API title to be displayed on the API homepage.
+* `:description`: A description of the API.
+* `:contact`: Contact email.
+* `:license`: The name of the license.
+* `:license_url`: The URL of the license.
+* `:terms_of_service_url`: The URL of the API terms and conditions.
+
+#### api_documentation
+
+Customize the Swagger API documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description".
+
+``` ruby
+add_swagger_documentation \
+   api_documentation: { desc: 'Reticulated splines API swagger-compatible documentation.' }
+```
+
+#### specific_api_documentation
+
+Customize the Swagger API specific documentation route, typically contains a `desc` field. The default description is "Swagger compatible API description for specific API".
+
+``` ruby
+add_swagger_documentation \
+   specific_api_documentation: { desc: 'Reticulated splines API swagger-compatible endpoint documentation.' }
+```
+
+## Swagger Header Parameters
+
+Swagger also supports the documentation of parameters passed in the header. Since grape's ```params[]``` doesn't return header parameters we can specify header parameters seperately in a block after the description.
+
+``` ruby
+desc "Return super-secret information", {
+  headers: {
+    "XAuthToken" => {
+      description: "Valdates your identity",
+      required: true
+    },
+    "XOptionalHeader" => {
+      description: "Not really needed",
+      required: false
+    }
+  }
+}
+```
+
+## Hiding an Endpoint
+
+You can hide an endpoint by adding ```hidden: true``` in the description of the endpoint:
+
+``` ruby
+desc 'Hide this endpoint', hidden: true
+```
+
+## Overriding Auto-Generated Nicknames
+
+You can specify a swagger nickname to use instead of the auto generated name by adding `:nickname 'string'``` in the description of the endpoint.
+
+``` ruby
+desc 'Get a full list of pets', nickname: 'getAllPets'
+```
+
+## Grape Entities
+
+Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to our Gemfile.
+
+The following example exposes statuses. And exposes statuses documentation adding :type and :desc.
+
+```ruby
+module API
+  module Entities
+    class Status < Grape::Entity
+      expose :text, documentation: { type: 'string', desc: 'Status update text.' }
+      expose :links, using: Link, documentation: { type: 'link', is_array: true }
+      expose :numbers, documentation: { type: 'integer', desc: 'favourite number', values: [1,2,3,4] }
+    end
+
+    class Link < Grape::Entity
+      def self.entity_name
+        'link'
+      end
+
+      expose :href, documentation: { type: 'url' }
+      expose :rel, documentation: { type: 'string'}
+    end
+  end
+
+  class Statuses < Grape::API
+    version 'v1'
+
+    desc 'Statuses index', entity: API::Entities::Status
+    get '/statuses' do
+      statuses = Status.all
+      type = current_user.admin? ? :full : :default
+      present statuses, with: API::Entities::Status, type: type
+    end
+
+    desc 'Creates a new status', entity: API::Entities::Status, params: API::Entities::Status.documentation
+    post '/statuses' do
+        ...
+    end
+  end
+end
+```
+
+### Relationships
+
+#### 1xN
+
+```ruby
+module API
+  module Entities
+    class Client < Grape::Entity
+      expose :name, documentation: { type: 'string', desc: 'Name' }
+      expose :addresses, using: Entities::Address,
+        documentation: { type: 'Address', desc: 'Addresses.', param_type: 'body', is_array: true }
+    end
+
+    class Address < Grape::Entity
+      expose :street, documentation: { type: 'string', desc: 'Street.' }
+    end
+  end
+
+  class Clients < Grape::API
+    version 'v1'
+
+    desc 'Clients index', params: Entities::Client.documentation
+    get '/clients' do
+      ...
+    end
+  end
+
+  add_swagger_documentation models: [Entities::Client, Entities::Address]
+end
+```
+
+#### 1x1
+
+Note: `is_array` is `false` by default.
+
+```ruby
+module API
+  module Entities
+    class Client < Grape::Entity
+      expose :name, documentation: { type: 'string', desc: 'Name' }
+      expose :address, using: Entities::Address,
+        documentation: { type: 'Address', desc: 'Addresses.', param_type: 'body', is_array: false }
+    end
+
+    class Address < Grape::Entity
+      expose :street, documentation: { type: 'string', desc: 'Street' }
+    end
+  end
+
+  class Clients < Grape::API
+    version 'v1'
+
+    desc 'Clients index', params: Entities::Client.documentation
+    get '/clients' do
+      ...
+    end
+  end
+
+  add_swagger_documentation models: [Entities::Client, Entities::Address]
+end
+```
+
+## Markdown in Notes
+
+The grape-swagger gem allows you to add an explanation in markdown in the notes field. Which would result in proper formatted markdown in Swagger UI.
+Grape-swagger uses adapters for several markdown formatters. It includes adapters for [kramdown](http://kramdown.rubyforge.org) (kramdown [syntax](http://kramdown.rubyforge.org/syntax.html)) and [redcarpet](https://github.com/vmg/redcarpet).
+The adapters are packed in the GrapeSwagger::Markdown modules. We do not include the markdown gems in our gemfile, so be sure to include or install the depended gems.
+
+
+### Kramdown
+If you want to use kramdown as markdown formatter, you need to add kramdown to your gemfile.
+
+```
+gem 'kramdown'
+```
+
+Configure your api documentation route with:
+
+
+``` ruby
+add_swagger_documentation(
+  markdown: GrapeSwagger::Markdown::KramdownAdapter
+)
+```
+
+Finally you can write endpoint descriptions the with markdown enabled.
+
+``` ruby
+desc "Reserve a virgin in heaven", {
+  notes: <<-NOTE
+    Virgins in Heaven
+    -----------------
+
+    > A virgin doesn't come for free
+
+    If you want to reserve a virgin in heaven, you have to do
+    some crazy stuff on earth.
+
+        def do_good
+          puts 'help people'
+        end
+
+    * _Will go to Heaven:_ Probably
+    * _Will go to Hell:_ Probably not
+  NOTE
+}
+```
+
+### Redcarpet
+As alternative you can use [redcarpet](https://github.com/vmg/redcarpet) as formatter, you need to include redcarpet in your gemspec. If you also want to use [rouge](https://github.com/jneen/rouge) as syntax highlighter you also need to include it.
+
+```
+gem 'redcarpet'
+gem 'rouge'
+```
+
+Configure your api documentation route with:
+
+``` ruby
+add_swagger_documentation(
+  markdown: GrapeSwagger::Markdown::RedcarpetAdapter.new(render_options: { highlighter: :rouge })
+)
+```
+
+Alternatively you can disable rouge by adding `:none` as highlighter option. You can add redcarpet extensions and render options trough the `extenstions:` and `render_options:` parameters.
+
+### Custom markdown formatter
+You can also add your custom adapter for your favourite markdown formatter, as long it responds to the method `markdown(text)` and it formats the given text.
+
+``` ruby
+module API
+
+  class MySuperbMarkdownFormatterAdapter
+   attr_reader :adapter
+
+   def initialize(options)
+    require 'superbmarkdownformatter'
+    @adapter = SuperbMarkdownFormatter.new options
+   end
+
+   def markdown(text)
+      @adapter.render_supreme(text)
+   end
+  end
+
+  add_swagger_documentation markdown: MySuperbMarkdownFormatterAdapter.new(no_links: true)
+end
+
+```
+
+## Response documentation
+
+You can also document the HTTP status codes with a description and a specified model that your API returns with the following syntax.
+
+``` ruby
+get '/', http_codes: [
+  [200, 'Ok', Entities::Client],
+  [400, "Invalid parameter entry"]
+] do
+  ...
+end
+```
+
+## Contributing to grape-swagger
+
+See [CONTRIBUTING](CONTRIBUTING.md).
+
+## Copyright and License
+
+Copyright (c) 2012-2014 Tim Vandecasteele and contributors. See [LICENSE.txt](LICENSE.txt) for details.