Added UPGRADING instructions.

Support instantiating the markdown adapeter without creating an instance.

CHANGELOG.md

@@ -1,24 +1,31 @@
-### Next Release
+### 0.8.0 (August 27, 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).
-* [#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).
 * [#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).
-* Rewritten .gemspec and removed Jeweler - [@dblock](https://github.com/dblock).
-* Added `GrapeEntity::VERSION` - [@dblock](https://github.com/dblock).
-* Added Rubocop, Ruby-style linter - [@dblock](https://github.com/dblock).
-* [#126](https://github.com/tim-vandecasteele/grape-swagger/pull/126): Rewritten demo in the `test` folder with CORS enabled - [@dblock](https://github.com/dblock).
-* [#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).
 * [#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).
-* [#135](https://github.com/tim-vandecasteele/grape-swagger/pull/135): Fixed model inclusion in models with aliased references - [@cdarne](https://github.com/cdarne).
 * [#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).
-* Your Contribution Here
+
+#### 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)
 

README.md

@@ -19,6 +19,10 @@ 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.
@@ -212,7 +216,7 @@ module API
       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
         ...
@@ -290,7 +294,7 @@ Grape-swagger uses adapters for several markdown formatters. It includes adapter
 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 
+### Kramdown
 If you want to use kramdown as markdown formatter, you need to add kramdown to your gemfile.
 
 ```
@@ -302,11 +306,11 @@ Configure your api documentation route with:
 
 ``` ruby
 add_swagger_documentation(
-  markdown: GrapeSwagger::Markdown::KramdownAdapter.new
+  markdown: GrapeSwagger::Markdown::KramdownAdapter
 )
 ```
 
-Finally you can write endpoint descriptions the with markdown enabled. 
+Finally you can write endpoint descriptions the with markdown enabled.
 
 ``` ruby
 desc "Reserve a virgin in heaven", {
@@ -334,7 +338,7 @@ As alternative you can use [redcarpet](https://github.com/vmg/redcarpet) as form
 
 ```
 gem 'redcarpet'
-gem 'rouge'   
+gem 'rouge'
 ```
 
 Configure your api documentation route with:
@@ -352,21 +356,21 @@ You can also add your custom adapter for your favourite markdown formatter, as l
 
 ``` 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 } 
+  add_swagger_documentation markdown: MySuperbMarkdownFormatterAdapter, { no_links: true }
 end
 
 ```

UPGRADING.md

@@ -0,0 +1,47 @@
+Upgrading Grape-swagger
+=======================
+
+### Upgrading to >= 0.8.0
+
+#### Changes in Configuration
+
+The following options have been added, removed or have been changed in the grape-swagger interface:
+
+* `markdown: true/false` => `markdown: GrapeSwagger::Markdown::KramdownAdapter`
+
+#### Markdown
+
+You can now configure a markdown adapter. This was originally changed because of performance issues with Kramdown and the `markdown` option no longer takes a boolean argument. Built-in adapters include Kramdown and Redcarpet.
+
+##### Kramdown
+
+To configure the markdown with Kramdown, add the kramdown gem to your Gemfile:
+
+`gem 'kramdown'`
+
+Configure grape-swagger as follows:
+
+```ruby
+add_swagger_documentation (
+    markdown: GrapeSwagger::Markdown::KramdownAdapter
+)
+```
+
+#### Redcarpet
+
+To configure markdown with Redcarpet, add the redcarpet and the rouge gem to your Gemfile. Note that Redcarpet does not work with JRuby.
+
+```ruby
+gem 'redcarpet'
+gem 'rouge'
+```
+
+Configure grape-swagger as follows:
+
+```ruby
+add_swagger_documentation (
+    markdown: GrapeSwagger::Markdown::RedcarpetAdapter
+)
+```
+
+See [#142](https://github.com/tim-vandecasteele/grape-swagger/pull/142) and documentation section [Markdown in Notes](https://github.com/tim-vandecasteele/grape-swagger#markdown-in-notes) for more information.

lib/grape-swagger/markdown.rb

@@ -8,6 +8,7 @@ module GrapeSwagger
     # The adapters are responsible of loading the required markdown dependencies and throw errors.
     ###
     def initialize(adapter)
+      adapter = adapter.new if adapter.is_a?(Class)
       fail(ArgumentError, "The configured markdown adapter should implement the method #{ :markdown }") unless adapter.respond_to? :markdown
       @adapter = adapter
     end

lib/grape-swagger/version.rb

@@ -1,3 +1,3 @@
 module GrapeSwagger
-  VERSION = '0.7.2'
+  VERSION = '0.8.0'
 end

spec/non_default_api_spec.rb

@@ -394,18 +394,46 @@ describe 'options: ' do
       end
     end
 
+    subject do
+      Class.new(Grape::API) do
+        mount MarkDownMountedApi
+      end
+    end
+
     def app
       SimpleApiWithMarkdown
     end
 
-    it 'parses markdown for a mounted-api' do
+    context 'with instance' do
-      get '/swagger_doc/something.json'
+      before do
-      expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
+        subject.add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter.new, info: { description: '_test_' }
+      end
+
+      it 'parses markdown for a mounted-api' do
+        get '/swagger_doc/something.json'
+        expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
+      end
+
+      it 'parses markdown for swagger info' do
+        get '/swagger_doc.json'
+        expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
+      end
     end
 
-    it 'parses markdown for swagger info' do
+    context 'with class' do
-      get '/swagger_doc.json'
+      before do
-      expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
+        subject.add_swagger_documentation markdown: GrapeSwagger::Markdown::KramdownAdapter, info: { description: '_test_' }
+      end
+
+      it 'parses markdown for a mounted-api' do
+        get '/swagger_doc/something.json'
+        expect(JSON.parse(last_response.body)['apis'][0]['operations'][0]['notes']).to eq("<p><em>test</em></p>\n")
+      end
+
+      it 'parses markdown for swagger info' do
+        get '/swagger_doc.json'
+        expect(JSON.parse(last_response.body)['info']).to eq('description' => "<p><em>test</em></p>\n")
+      end
     end
   end