Map clearly Grape desc/detail to Swagger summary/description

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 * [#558](https://github.com/ruby-grape/grape-swagger/pull/558): Version cascading including dependency updates (includes: [LeFnord#27](https://github.com/LeFnord/grape-swagger/pull/27)) - [@LeFnord](https://github.com/LeFnord).
 * [#535](https://github.com/ruby-grape/grape-swagger/pull/535): Add support for grape version cascading  - [@qinix](https://github.com/qinix).
+* [#560](https://github.com/ruby-grape/grape-swagger/pull/560): Map clearly Grape desc/detail to Swagger summary/description - [@frodrigo](https://github.com/frodrigo).
 
 * Your contribution here.
 

lib/grape-swagger/endpoint.rb

@@ -131,10 +131,8 @@ def summary_object(route)
     end
 
     def description_object(route, markdown)
-      description = route.options[:desc] if route.options.key?(:desc)
       description = route.description if route.description.present?
-      description = "# #{description} " if markdown
-      description += "\n #{route.options[:detail]}" if route.options.key?(:detail)
+      description = route.options[:detail] if route.options.key?(:detail)
       description = markdown.markdown(description.to_s).chomp if markdown
 
       description

spec/swagger_v2/api_swagger_v2_detail_spec.rb

@@ -61,13 +61,17 @@ def app
     end
 
     specify do
+      expect(subject['paths']['/use_detail']['get']).to include('summary')
+      expect(subject['paths']['/use_detail']['get']['summary']).to eql "This returns something"
       expect(subject['paths']['/use_detail']['get']).to include('description')
-      expect(subject['paths']['/use_detail']['get']['description']).to eql "This returns something\n detailed description of the route"
+      expect(subject['paths']['/use_detail']['get']['description']).to eql "detailed description of the route"
     end
 
     specify do
+      expect(subject['paths']['/use_detail_block']['get']).to include('summary')
+      expect(subject['paths']['/use_detail_block']['get']['summary']).to eql "This returns something"
       expect(subject['paths']['/use_detail_block']['get']).to include('description')
-      expect(subject['paths']['/use_detail_block']['get']['description']).to eql "This returns something\n detailed description of the route inside the `desc` block"
+      expect(subject['paths']['/use_detail_block']['get']['description']).to eql "detailed description of the route inside the `desc` block"
     end
   end
 
@@ -104,7 +108,7 @@ def app
     specify do
       expect(subject['paths']['/use_gfm_detail']['get']).to include('description')
       expect(subject['paths']['/use_gfm_detail']['get']['description']).to eql(
-        "<h1 id=\"this-returns-something\">This returns something</h1>\n<p># Burgers in Heaven</p>\n\n<blockquote>\n  <p>A burger doesn’t come for free</p>\n</blockquote>\n\n<p>If you want to reserve a burger in heaven, you have to do<br />\nsome crazy stuff on earth.</p>\n\n<pre><code>def do_good\nputs 'help people'\nend\n</code></pre>\n\n<ul>\n  <li><em>Will go to Heaven:</em> Probably</li>\n  <li><em>Will go to Hell:</em> Probably not</li>\n</ul>"
+        "<h1 id=\"burgers-in-heaven\">Burgers in Heaven</h1>\n\n<blockquote>\n  <p>A burger doesn’t come for free</p>\n</blockquote>\n\n<p>If you want to reserve a burger in heaven, you have to do<br />\nsome crazy stuff on earth.</p>\n\n<pre><code>def do_good\nputs 'help people'\nend\n</code></pre>\n\n<ul>\n  <li><em>Will go to Heaven:</em> Probably</li>\n  <li><em>Will go to Hell:</em> Probably not</li>\n</ul>"
       )
     end
   end
@@ -117,6 +121,7 @@ module TheApi
         class GfmRcDetailApi < Grape::API
           format :json
 
+
           desc 'This returns something',
                detail: details,
                entity: Entities::UseResponse,
@@ -142,7 +147,7 @@ def app
     specify do
       expect(subject['paths']['/use_gfm_rc_detail']['get']).to include('description')
       expect(subject['paths']['/use_gfm_rc_detail']['get']['description']).to eql(
-        "<h1>This returns something</h1>\n\n<p># Burgers in Heaven</p>\n\n<blockquote>\n<p>A burger doesn&#39;t come for free</p>\n</blockquote>\n\n<p>If you want to reserve a burger in heaven, you have to do\nsome crazy stuff on earth.</p>\n<pre class=\"highlight plaintext\"><code>def do_good\nputs 'help people'\nend\n</code></pre>\n<ul>\n<li><em>Will go to Heaven:</em> Probably</li>\n<li><em>Will go to Hell:</em> Probably not</li>\n</ul>"
+        "<h1>Burgers in Heaven</h1>\n\n<blockquote>\n<p>A burger doesn&#39;t come for free</p>\n</blockquote>\n\n<p>If you want to reserve a burger in heaven, you have to do\nsome crazy stuff on earth.</p>\n<pre class=\"highlight plaintext\"><code>def do_good\nputs 'help people'\nend\n</code></pre>\n<ul>\n<li><em>Will go to Heaven:</em> Probably</li>\n<li><em>Will go to Hell:</em> Probably not</li>\n</ul>"
       )
     end
   end

spec/swagger_v2/namespaced_api_spec.rb

@@ -16,8 +16,8 @@ def app
       JSON.parse(last_response.body)['paths']['/aspace']['get']
     end
 
-    it 'shows the namespace description in the json spec' do
-      expect(subject['description']).to eql('Description for aspace')
+    it 'shows the namespace summary in the json spec' do
+      expect(subject['summary']).to eql('Description for aspace')
     end
   end
 
@@ -36,8 +36,8 @@ def app
       JSON.parse(last_response.body)['paths']['/camelCases']['get']
     end
 
-    it 'shows the namespace description in the json spec' do
-      expect(subject['description']).to eql('Look! An endpoint.')
+    it 'shows the namespace summary in the json spec' do
+      expect(subject['summary']).to eql('Look! An endpoint.')
     end
   end
 
@@ -60,8 +60,8 @@ def app
       JSON.parse(last_response.body)['paths']['/bspace']['get']
     end
 
-    it 'shows the namespace description in the json spec' do
-      expect(subject['description']).to eql('Description for aspace')
+    it 'shows the namespace summary in the json spec' do
+      expect(subject['summary']).to eql('Description for aspace')
     end
   end
 
@@ -84,8 +84,8 @@ def app
       JSON.parse(last_response.body)['paths']['/mounted/bspace']['get']
     end
 
-    it 'shows the namespace description in the json spec' do
-      expect(subject['description']).to eql('Description for aspace')
+    it 'shows the namespace summary in the json spec' do
+      expect(subject['summary']).to eql('Description for aspace')
     end
   end
 
@@ -112,8 +112,8 @@ def app
       JSON.parse(last_response.body)['paths']['/mounted/bspace']['get']
     end
 
-    it 'shows the namespace description in the json spec' do
-      expect(subject['description']).to eql('Description for aspace')
+    it 'shows the namespace summary in the json spec' do
+      expect(subject['summary']).to eql('Description for aspace')
     end
   end
 end