Add 'summary' for further object compliance with OpenAPI v2 (#434)

ruby-grape · May 23, 2016 · dd4ba4a · dd4ba4a
1 parent 677714b
commit dd4ba4a
Show file tree

Hide file tree

Showing 13 changed files with 86 additions and 3 deletions.
diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml
@@ -28,7 +28,7 @@ Metrics/AbcSize:
 # Offense count: 3
 # Configuration parameters: CountComments.
 Metrics/ClassLength:
-  Max: 201
+  Max: 206
 
 # Offense count: 10
 Metrics/CyclomaticComplexity:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 #### Features
 
+* [#434](https://github.com/ruby-grape/grape-swagger/pull/434): Add summary to the operation object generator to be more compliant with [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object) - [@aschuster3](https://github.com/aschuster3).
 * Your contribution here.
 
 #### Fixes

diff --git a/README.md b/README.md
@@ -444,6 +444,32 @@ end
 ```
 
 
+#### Overriding the route summary
+
+By default, the route summary is filled with the value supplied to `desc`.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary'
+  get :order_id do
+    ...
+  end
+end
+```
+
+To override the summary, add `summary: '[string]'` after the description.
+
+```ruby
+namespace 'order' do
+  desc 'This will be your summary',
+    summary: 'Now this is your summary!'
+  get :order_id do
+    ...
+  end
+end
+```
+
+
 #### Expose nested namespace as standalone route
 
 Use the `nested: false` property in the `swagger` option to make nested namespaces appear as standalone resources.

diff --git a/lib/grape-swagger/endpoint.rb b/lib/grape-swagger/endpoint.rb
@@ -103,6 +103,7 @@ def path_item(routes, options)
 
     def method_object(route, options, path)
       method = {}
+      method[:summary]     = summary_object(route)
       method[:description] = description_object(route, options[:markdown])
       method[:produces]    = produces_object(route, options[:produces] || options[:format])
       method[:consumes]    = consumes_object(route, options[:format])
@@ -115,6 +116,14 @@ def method_object(route, options, path)
       [route.request_method.downcase.to_sym, method]
     end
 
+    def summary_object(route)
+      summary = route.options[:desc] if route.options.key?(:desc)
+      summary = route.description if route.description.present?
+      summary = route.options[:summary] if route.options.key?(:summary)
+
+      summary
+    end
+
     def description_object(route, markdown)
       description = route.options[:desc] if route.options.key?(:desc)
       description = route.description if route.description.present?
@@ -237,9 +246,7 @@ def expose_params_from_model(model)
 
       GrapeSwagger.model_parsers.each do |klass, ancestor|
         next unless model.ancestors.map(&:to_s).include?(ancestor)
-
         parser = klass.new(model, self)
-
         break
       end
 

diff --git a/spec/issues/403_versions_spec.rb b/spec/issues/403_versions_spec.rb
@@ -29,6 +29,7 @@ def app
         paths: {
           :'/nothings' => {
             get: {
+              summary: 'no versions given',
               description: 'no versions given',
               produces: ['application/json'],
               responses: {
@@ -71,6 +72,7 @@ def app
         paths: {
           :'/v2/api_version' => {
             get: {
+              summary: 'api versions given',
               description: 'api versions given',
               produces: ['application/json'],
               responses: {
@@ -112,6 +114,7 @@ def app
         paths: {
           :'/doc_version' => {
             get: {
+              summary: 'doc versions given',
               description: 'doc versions given',
               produces: ['application/json'],
               responses: {
@@ -154,6 +157,7 @@ def app
         paths: {
           :'/v2/both_versions' => {
             get: {
+              summary: 'both versions given',
               description: 'both versions given',
               produces: ['application/json'],
               responses: {

diff --git a/spec/support/model_parsers/entity_parser.rb b/spec/support/model_parsers/entity_parser.rb
@@ -192,6 +192,7 @@ class RecursiveModel < Grape::Entity
       'paths' => {
         '/v3/other_thing/{elements}' => {
           'get' => {
+            'summary' => 'nested route inside namespace',
             'description' => 'nested route inside namespace',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -204,6 +205,7 @@ class RecursiveModel < Grape::Entity
         },
         '/thing' => {
           'get' => {
+            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'parameters' => [
@@ -217,6 +219,7 @@ class RecursiveModel < Grape::Entity
             'operationId' => 'getThing'
           },
           'post' => {
+            'summary' => 'This creates Thing.',
             'description' => 'This creates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -231,6 +234,7 @@ class RecursiveModel < Grape::Entity
         },
         '/thing/{id}' => {
           'get' => {
+            'summary' => 'This gets Thing.',
             'description' => 'This gets Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -239,6 +243,7 @@ class RecursiveModel < Grape::Entity
             'operationId' => 'getThingId'
           },
           'put' => {
+            'summary' => 'This updates Thing.',
             'description' => 'This updates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -252,6 +257,7 @@ class RecursiveModel < Grape::Entity
             'operationId' => 'putThingId'
           },
           'delete' => {
+            'summary' => 'This deletes Thing.',
             'description' => 'This deletes Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -262,6 +268,7 @@ class RecursiveModel < Grape::Entity
         },
         '/thing2' => {
           'get' => {
+            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -271,6 +278,7 @@ class RecursiveModel < Grape::Entity
         },
         '/dummy/{id}' => {
           'delete' => {
+            'summary' => 'dummy route.',
             'description' => 'dummy route.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

diff --git a/spec/support/model_parsers/mock_parser.rb b/spec/support/model_parsers/mock_parser.rb
@@ -184,6 +184,7 @@ class RecursiveModel < OpenStruct; end
       'paths' => {
         '/v3/other_thing/{elements}' => {
           'get' => {
+            'summary' => 'nested route inside namespace',
             'description' => 'nested route inside namespace',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -196,6 +197,7 @@ class RecursiveModel < OpenStruct; end
         },
         '/thing' => {
           'get' => {
+            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'parameters' => [
@@ -209,6 +211,7 @@ class RecursiveModel < OpenStruct; end
             'operationId' => 'getThing'
           },
           'post' => {
+            'summary' => 'This creates Thing.',
             'description' => 'This creates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -223,6 +226,7 @@ class RecursiveModel < OpenStruct; end
         },
         '/thing/{id}' => {
           'get' => {
+            'summary' => 'This gets Thing.',
             'description' => 'This gets Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -231,6 +235,7 @@ class RecursiveModel < OpenStruct; end
             'operationId' => 'getThingId'
           },
           'put' => {
+            'summary' => 'This updates Thing.',
             'description' => 'This updates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -244,6 +249,7 @@ class RecursiveModel < OpenStruct; end
             'operationId' => 'putThingId'
           },
           'delete' => {
+            'summary' => 'This deletes Thing.',
             'description' => 'This deletes Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -254,6 +260,7 @@ class RecursiveModel < OpenStruct; end
         },
         '/thing2' => {
           'get' => {
+            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -263,6 +270,7 @@ class RecursiveModel < OpenStruct; end
         },
         '/dummy/{id}' => {
           'delete' => {
+            'summary' => 'dummy route.',
             'description' => 'dummy route.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

diff --git a/spec/support/model_parsers/representable_parser.rb b/spec/support/model_parsers/representable_parser.rb
@@ -261,6 +261,7 @@ class RecursiveModel < Representable::Decorator
       'paths' => {
         '/v3/other_thing/{elements}' => {
           'get' => {
+            'summary' => 'nested route inside namespace',
             'description' => 'nested route inside namespace',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'body', 'name' => 'elements', 'description' => 'Set of configuration', 'type' => 'array', 'items' => { 'type' => 'string' }, 'required' => true }],
@@ -273,6 +274,7 @@ class RecursiveModel < Representable::Decorator
         },
         '/thing' => {
           'get' => {
+            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'parameters' => [
@@ -286,6 +288,7 @@ class RecursiveModel < Representable::Decorator
             'operationId' => 'getThing'
           },
           'post' => {
+            'summary' => 'This creates Thing.',
             'description' => 'This creates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -300,6 +303,7 @@ class RecursiveModel < Representable::Decorator
         },
         '/thing/{id}' => {
           'get' => {
+            'summary' => 'This gets Thing.',
             'description' => 'This gets Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -308,6 +312,7 @@ class RecursiveModel < Representable::Decorator
             'operationId' => 'getThingId'
           },
           'put' => {
+            'summary' => 'This updates Thing.',
             'description' => 'This updates Thing.',
             'produces' => ['application/json'],
             'consumes' => ['application/json'],
@@ -321,6 +326,7 @@ class RecursiveModel < Representable::Decorator
             'operationId' => 'putThingId'
           },
           'delete' => {
+            'summary' => 'This deletes Thing.',
             'description' => 'This deletes Thing.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],
@@ -331,6 +337,7 @@ class RecursiveModel < Representable::Decorator
         },
         '/thing2' => {
           'get' => {
+            'summary' => 'This gets Things.',
             'description' => 'This gets Things.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'get Horses', 'schema' => { '$ref' => '#/definitions/Something' } }, '401' => { 'description' => 'HorsesOutError', 'schema' => { '$ref' => '#/definitions/ApiError' } } },
@@ -340,6 +347,7 @@ class RecursiveModel < Representable::Decorator
         },
         '/dummy/{id}' => {
           'delete' => {
+            'summary' => 'dummy route.',
             'description' => 'dummy route.',
             'produces' => ['application/json'],
             'parameters' => [{ 'in' => 'path', 'name' => 'id', 'type' => 'integer', 'format' => 'int32', 'required' => true }],

diff --git a/spec/swagger_v2/api_swagger_v2_response_spec.rb b/spec/swagger_v2/api_swagger_v2_response_spec.rb
@@ -45,6 +45,7 @@ def app
     end
     specify do
       expect(subject['paths']['/nested_type']['get']).to eql(
+        'summary' => 'This returns something',
         'description' => 'This returns something',
         'produces' => ['application/json'],
         'responses' => {
@@ -66,6 +67,7 @@ def app
 
     specify do
       expect(subject['paths']['/entity_response']['get']).to eql(
+        'summary' => 'This returns something',
         'description' => 'This returns something',
         'produces' => ['application/json'],
         'responses' => {
@@ -87,6 +89,7 @@ def app
 
     specify do
       expect(subject['paths']['/params_response']['post']).to eql(
+        'summary' => 'This returns something',
         'description' => 'This returns something',
         'produces' => ['application/json'],
         'consumes' => ['application/json'],

diff --git a/spec/swagger_v2/default_api_spec.rb b/spec/swagger_v2/default_api_spec.rb
@@ -29,6 +29,7 @@ def app
         'paths' => {
           '/something' => {
             'get' => {
+              'summary' => 'This gets something.',
               'description' => 'This gets something.',
               'produces' => ['application/json'],
               'tags' => ['something'],
@@ -75,6 +76,7 @@ def app
                             'paths' => {
                               '/something' => {
                                 'get' => {
+                                  'summary' => 'This gets something.',
                                   'description' => 'This gets something.',
                                   'produces' => ['application/json'],
                                   'tags' => ['something'],

diff --git a/spec/swagger_v2/hide_api_spec.rb b/spec/swagger_v2/hide_api_spec.rb
@@ -44,6 +44,7 @@ def app
       'paths' => {
         '/simple' => {
           'get' => {
+            'summary' => 'Show this endpoint',
             'description' => 'Show this endpoint',
             'produces' => ['application/json'],
             'tags' => ['simple'],
@@ -53,6 +54,7 @@ def app
         },
         '/lazy' => {
           'get' => {
+            'summary' => 'Lazily show endpoint',
             'description' => 'Lazily show endpoint',
             'produces' => ['application/json'],
             'tags' => ['lazy'],
@@ -105,6 +107,7 @@ def app
       'paths' => {
         '/simple/show' => {
           'get' => {
+            'summary' => 'Show this endpoint',
             'description' => 'Show this endpoint',
             'produces' => ['application/json'],
             'operationId' => 'getSimpleShow',
@@ -126,6 +129,7 @@ def app
       'paths' => {
         '/simple/show' => {
           'get' => {
+            'summary' => 'Show this endpoint',
             'description' => 'Show this endpoint',
             'produces' => ['application/json'],
             'tags' => ['simple'],

diff --git a/spec/swagger_v2/mounted_target_class_spec.rb b/spec/swagger_v2/mounted_target_class_spec.rb
@@ -37,6 +37,7 @@ def app
       'paths' => {
         '/simple' => {
           'get' => {
+            'summary' => 'This gets something.',
             'description' => 'This gets something.',
             'produces' => ['application/json'],
             'responses' => { '200' => { 'description' => 'This gets something.' } },
@@ -59,6 +60,7 @@ def app
       'paths' => {
         '/simple' => {
           'get' => {
+            'summary' => 'This gets something.',
             'description' => 'This gets something.',
             'produces' => ['application/json'],
             'responses' => {