Use `detail` option as `notes` value.

This adds support for using the `detail` value defined within a block passed to `desc` as `notes` value exposed in swagger doc.

CAUTION: only works on grape version > 0.10.0
```
$ GRAPE_VERSION=HEAD bundle exec rspec ./spec/default_api_spec.rb:62
```

fixes #212

CHANGELOG.md

@@ -20,7 +20,8 @@
 * [#206](https://github.com/tim-vandecasteele/grape-swagger/pull/206): Fixed 'is_array' in the return entity being ignored - [@igormoochnick](https://github.com/igormoochnick).
 * [#266](https://github.com/tim-vandecasteele/grape-swagger/pull/266): Respect primitive mapping on type and format attributes of 1.2 swagger spec - [@frodrigo](https://github.com/frodrigo).
 * [#268](https://github.com/tim-vandecasteele/grape-swagger/pull/268): Fixed handling of `type: Array[...]` - [@frodrigo](https://github.com/frodrigo).
-* [#284](https://github.com/tim-vandecasteele/grape-swagger/pull/284): Use new params syntax for swagger doc endpoint, fix an issue that `:name` params not recognized by `declared` method -[@calfzhou](https://github.com/calfzhou).
+* [#284](https://github.com/tim-vandecasteele/grape-swagger/pull/284): Use new params syntax for swagger doc endpoint, fix an issue that `:name` params not recognized by `declared` method - [@calfzhou](https://github.com/calfzhou).
+* [#286](https://github.com/tim-vandecasteele/grape-swagger/pull/286): Use `detail` value for `notes` - fix an issue where `detail` value specified in a block passed to `desc` was ignored - [@rngtng](https://github.com/rngtng).
 
 ### 0.10.1 (March 11, 2015)
 

Gemfile

@@ -4,7 +4,7 @@ gemspec
 
 case version = ENV['GRAPE_VERSION'] || '~> 0.9.0'
 when 'HEAD'
-  gem 'grape', github: 'intridea/grape'
+  gem 'grape', github: 'ruby-grape/grape'
 else
   gem 'grape', version
 end

README.md

@@ -90,7 +90,7 @@ API class name.
 
 #### markdown
 
-Allow markdown in `notes`, default is `nil`. (disabled) See below for details.
+Allow markdown in `detail`/`notes`, default is `nil`. (disabled) See below for details.
 
 #### hide_format
 
@@ -205,11 +205,10 @@ desc 'Get a full list of pets', is_array: true
 
 ## Using an options hash
 
-The Grape DSL supports either an options hash or a restricted block to pass settings. Passing the `nickname`, `hidden` and `is_array` options together with response codes is only possible when passing an options hash. 
+The Grape DSL supports either an options hash or a restricted block to pass settings. Passing the `nickname`, `hidden` and `is_array` options together with response codes is only possible when passing an options hash.
 Since the syntax differs you'll need to adjust it accordingly:
 
 ``` ruby
-
 desc 'Get all kittens!', {
   :hidden => true,
   :is_array => true,
@@ -220,6 +219,17 @@ desc 'Get all kittens!', {
 get '/kittens' do
 ```
 
+## Specify endpoint details
+
+To specify further details for an endpoint, use the `detail` option within a block passed to `desc`:
+
+``` ruby
+desc 'Get all kittens!' do
+  detail 'this will expose all the kittens'
+end
+get '/kittens' do
+```
+
 ## Overriding param type
 
 You can override paramType in POST|PUT methods to query, using the documentation hash.
@@ -400,9 +410,9 @@ module API
 end
 ```
 
-## Markdown in Notes
+## Markdown in Detail/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.
+The grape-swagger gem allows you to add an explanation in markdown in the detail/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.
 
@@ -426,8 +436,8 @@ add_swagger_documentation(
 Finally you can write endpoint descriptions the with markdown enabled.
 
 ``` ruby
-desc "Reserve a burger in heaven", {
-  notes: <<-NOTE
+desc "Reserve a burger in heaven" do
+  detail <<-NOTE
     Veggie Burgers in Heaven
     -----------------
 
@@ -443,7 +453,7 @@ desc "Reserve a burger in heaven", {
     * _Will go to Heaven:_ Probably
     * _Will go to Hell:_ Probably not
   NOTE
-}
+end
 ```
 
 ### Redcarpet

UPGRADING.md

@@ -1,6 +1,23 @@
 Upgrading Grape-swagger
 =======================
 
+### Upgrading to >= 0.10.2
+
+With grape >= 0.12.0, support for `notes` is replaced by passing a block `detail` option specified. For future compatibility, update your code:
+
+```ruby
+desc 'Get all kittens!', notes: 'this will expose all the kittens'
+```
+
+to
+
+``` ruby
+ desc 'Get all kittens!' do
+  detail 'this will expose all the kittens'
+end
+```
+Be aware of https://github.com/ruby-grape/grape/issues/920, currently grape accepts either an option hash OR a block for `desc`.
+
 ### Upgrading to >= 0.9.0
 
 #### Grape-Swagger-Rails

lib/grape-swagger/doc_methods.rb

@@ -427,7 +427,7 @@ module GrapeSwagger
 
         ops.each do |path, op_routes|
           operations = op_routes.map do |route|
-            notes       = @@documentation_class.as_markdown(route.route_notes)
+            notes       = @@documentation_class.as_markdown(route.route_detail || route.route_notes)
 
             http_codes  = @@documentation_class.parse_http_codes(route.route_http_codes, models)
 

spec/default_api_spec.rb

@@ -1,4 +1,5 @@
 require 'spec_helper'
+require 'grape_version'
 
 describe 'Default API' do
   context 'with no additional options' do
@@ -38,6 +39,47 @@ describe 'Default API' do
         end
       end
     end
+
+  end
+  context 'with additional option block given to desc', if: GrapeVersion.satisfy?('>= 0.12.0')  do
+    def app
+      Class.new(Grape::API) do
+        format :json
+        desc 'This gets something.' do
+          detail 'more details about the endpoint'
+        end
+        get '/something' do
+          { bla: 'something' }
+        end
+        add_swagger_documentation
+      end
+    end
+
+    subject do
+      get '/swagger_doc/something'
+      JSON.parse(last_response.body)
+    end
+
+    it 'documents endpoint' do
+      expect(subject).to eq(
+        'apiVersion'     => '0.1',
+        'swaggerVersion' => '1.2',
+        'basePath'       => 'http://example.org',
+        'produces'       => ['application/json'],
+        'resourcePath'   => '/something',
+        'apis'           => [{
+          'path' => '/something.{format}',
+          'operations' => [{
+            'notes'      => 'more details about the endpoint',
+            'summary'    => 'This gets something.',
+            'nickname'   => 'GET-something--json-',
+            'method'     => 'GET',
+            'parameters' => [],
+            'type'       => 'void'
+          }]
+        }]
+      )
+    end
   end
 
   context 'with additional info' do