Add support for markdown in notes field.

Author: tim-vandecasteele

Gemfile

@@ -4,6 +4,7 @@ source "http://rubygems.org"
 #   gem "activesupport", ">= 2.3.5"
 
 gem 'grape'
+gem 'kramdown'
 
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.

Gemfile.lock

@@ -52,6 +52,7 @@ GEM
       railties (>= 3.2.0, < 5.0)
       thor (~> 0.14)
     json (1.7.3)
+    kramdown (0.13.7)
     mail (2.4.4)
       i18n (>= 0.4.0)
       mime-types (~> 1.16)
@@ -126,6 +127,7 @@ DEPENDENCIES
   grape
   jeweler (~> 1.8.4)
   jquery-rails
+  kramdown
   rack-test
   rails (~> 3.2)
   rdoc (~> 3.12)

README.markdown

@@ -41,6 +41,33 @@ You can pass a hash with some configuration possibilities to ```add_swagger_docu
 * ```:api_version``` Version of the API that's being exposed
 * ```:base_path``` Basepath of the API that's being exposed
 
+## Swagger additions
+grape-swagger allows you to add an explanation in markdown in the notes field. Which would result in proper formatted markdown in Swagger UI. The default Swagger UI doesn't allow HTML in the notes field, so you need to use an adapted version of Swagger UI (you can find one at https://github.com/tim-vandecasteele/swagger-ui/tree/vasco).
+
+We're using [kramdown](http://kramdown.rubyforge.org) for parsing the markdown, specific syntax can be found [here](http://kramdown.rubyforge.org/syntax.html).
+
+
+``` 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
+}
+```
+
 ## Contributing to grape-swagger
 
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

grape-swagger.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Tim Vandecasteele"]
-  s.date = "2012-07-27"
+  s.date = "2012-08-02"
   s.description = "A simple way to add proper auto generated documentation - that can be displayed with swagger - to your inline described grape API"
   s.email = "[email protected]"
   s.extra_rdoc_files = [
@@ -43,6 +43,7 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<grape>, [">= 0"])
+      s.add_runtime_dependency(%q<kramdown>, [">= 0"])
       s.add_development_dependency(%q<shoulda>, [">= 0"])
       s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_development_dependency(%q<bundler>, ["> 1.0.0"])
@@ -55,6 +56,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<rspec>, [">= 0"])
     else
       s.add_dependency(%q<grape>, [">= 0"])
+      s.add_dependency(%q<kramdown>, [">= 0"])
       s.add_dependency(%q<shoulda>, [">= 0"])
       s.add_dependency(%q<rdoc>, ["~> 3.12"])
       s.add_dependency(%q<bundler>, ["> 1.0.0"])
@@ -68,6 +70,7 @@ Gem::Specification.new do |s|
     end
   else
     s.add_dependency(%q<grape>, [">= 0"])
+    s.add_dependency(%q<kramdown>, [">= 0"])
     s.add_dependency(%q<shoulda>, [">= 0"])
     s.add_dependency(%q<rdoc>, ["~> 3.12"])
     s.add_dependency(%q<bundler>, ["> 1.0.0"])

lib/grape-swagger.rb

@@ -1,3 +1,5 @@
+require 'kramdown'
+
 module Grape
   class API
     class << self
@@ -68,17 +70,18 @@ def self.setup(options)
 
             desc 'Swagger compatible API description for specific API', :params =>
               {
-                "name" => { :desc => "Class name of mounted API", :type => "string", :required => true },
+                "name" => { :desc => "Resource name of mounted API", :type => "string", :required => true },
               }
             get "#{@@mount_path}/:name" do
               header['Access-Control-Allow-Origin'] = '*'
               header['Access-Control-Request-Method'] = '*'
               routes = @@target_class::combined_routes[params[:name]]
               routes_array = routes.map do |route|
+                notes = route.route_notes ? Kramdown::Document.new(route.route_notes.strip_heredoc).to_html : nil
                 {
                   :path => parse_path(route.route_path),
                   :operations => [{
-                    :notes => route.route_notes,
+                    :notes => notes,
                     :summary => route.route_description || '',
                     :nickname   => Random.rand(1000000),
                     :httpMethod => route.route_method,
@@ -129,3 +132,12 @@ def parse_path(path)
     end
   end
 end
+
+class String
+  # strip_heredoc from rails
+  # File activesupport/lib/active_support/core_ext/string/strip.rb, line 22
+  def strip_heredoc
+    indent = scan(/^[ \t]*(?=\S)/).min.try(:size) || 0
+    gsub(/^[ \t]{#{indent}}/, '')
+  end
+end