support extensions on the root object (ruby-grape#608)

* support extensions on the root object
* remove puts statement
* add spec for documentation
* tweaks for rubocop
* update changelog

Author: thogg4

CHANGELOG.md

@@ -3,6 +3,7 @@
 #### Features
 
 * Your contribution here.
+* [#608](https://github.com/ruby-grape/grape-swagger/pull/608): Support extensions on the root object - [@thogg4](https://github.com/thogg4).
 * [#596](https://github.com/ruby-grape/grape-swagger/pull/596): Use route_settings for hidden and operations extensions - [@thogg4](https://github.com/thogg4).
 * [#607](https://github.com/ruby-grape/grape-swagger/pull/607): Allow body parameter name to be specified - [@tjwp](https://github.com/tjwp).
 

README.md

@@ -906,11 +906,29 @@ end
 #### Extensions <a name="extensions" />
 
 Swagger spec2.0 supports extensions on different levels, for the moment,
-the documentation on `info`, `verb`, `path` and `definition` level would be supported.
+the documentation on the root level object and the `info`, `verb`, `path` and `definition` levels are supported.
 The documented key would be generated from the `x` + `-` + key of the submitted hash,
 for possibilities refer to the [extensions spec](spec/lib/extensions_spec.rb).
 To get an overview *how* the extensions would be defined on grape level, see the following examples:
 
+- root object extension, add a `x` key to the root hash when calling ```add_swagger_documentation```:
+```ruby
+  add_swagger_documentation \
+    x: {
+      some: 'stuff'
+    },
+    info: {
+    }
+```
+this would generate:
+```json
+{
+  "x-some": "stuff",
+  "info":{
+  }
+}
+```
+
 - `info` extension, add a `x` key to the `info` hash when calling ```add_swagger_documentation```:
 ```ruby
   add_swagger_documentation \

lib/grape-swagger/doc_methods/extensions.rb

@@ -16,6 +16,10 @@ def add(path, definitions, route)
           add_extensions_to_definition(settings, path, definitions) if settings && extended?(settings, :x_def)
         end
 
+        def add_extensions_to_root(settings, object)
+          add_extension_to(object, extension(settings)) if extended?(settings, :x)
+        end
+
         def add_extensions_to_info(settings, info)
           add_extension_to(info, extension(settings)) if extended?(settings, :x)
         end

lib/grape-swagger/endpoint.rb

@@ -23,17 +23,20 @@ def content_types_for(target_class)
     #
     # required keys for SwaggerObject
     def swagger_object(target_class, request, options)
-      {
-        info:           info_object(options[:info].merge(version: options[:doc_version])),
-        swagger:        '2.0',
-        produces:       content_types_for(target_class),
-        authorizations: options[:authorizations],
+      object = {
+        info:                info_object(options[:info].merge(version: options[:doc_version])),
+        swagger:             '2.0',
+        produces:            content_types_for(target_class),
+        authorizations:      options[:authorizations],
         securityDefinitions: options[:security_definitions],
-        security: options[:security],
-        host:           GrapeSwagger::DocMethods::OptionalObject.build(:host, options, request),
-        basePath:       GrapeSwagger::DocMethods::OptionalObject.build(:base_path, options, request),
-        schemes:        options[:schemes].is_a?(String) ? [options[:schemes]] : options[:schemes]
-      }.delete_if { |_, value| value.blank? }
+        security:            options[:security],
+        host:                GrapeSwagger::DocMethods::OptionalObject.build(:host, options, request),
+        basePath:            GrapeSwagger::DocMethods::OptionalObject.build(:base_path, options, request),
+        schemes:             options[:schemes].is_a?(String) ? [options[:schemes]] : options[:schemes]
+      }
+
+      GrapeSwagger::DocMethods::Extensions.add_extensions_to_root(options, object)
+      object.delete_if { |_, value| value.blank? }
     end
 
     # building info object

spec/swagger_v2/api_swagger_v2_extensions_spec.rb

@@ -58,7 +58,7 @@ class ExtensionsApi < Grape::API
           { 'declared_params' => declared(params) }
         end
 
-        add_swagger_documentation
+        add_swagger_documentation(x: { some: 'stuff' })
       end
     end
   end
@@ -67,6 +67,18 @@ def app
     TheApi::ExtensionsApi
   end
 
+  describe 'extension on root level' do
+    subject do
+      get '/swagger_doc/path_extension'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject).to include 'x-some'
+      expect(subject['x-some']).to eql 'stuff'
+    end
+  end
+
   describe 'extension on path level' do
     subject do
       get '/swagger_doc/path_extension'