Add an option to add root element to responses (#761)

Author: bikolya

CHANGELOG.md

@@ -3,9 +3,11 @@
 #### Features
 
 * Your contribution here.
+* [#761](https://github.com/ruby-grape/grape-swagger/pull/761): Add an option to configure root element for responses - [@bikolya](https://github.com/bikolya).
 
 #### Fixes
 
+* Your contribution here.
 * [#758](https://github.com/ruby-grape/grape-swagger/pull/758): Handle cases where a route's prefix is a nested URL - [@SimonKaluza](https://github.com/simonkaluza).
 * [#757](https://github.com/ruby-grape/grape-swagger/pull/757): Fix `array_use_braces` for nested body params - [@bikolya](https://github.com/bikolya).
 * [#756](https://github.com/ruby-grape/grape-swagger/pull/756): Fix reference creation when custom type for documentation is provided - [@bikolya](https://github.com/bikolya).

README.md

@@ -189,6 +189,7 @@ end
 * [base_path](#base_path)
 * [mount_path](#mount_path)
 * [add_base_path](#add_base_path)
+* [add_root](#add_root)
 * [add_version](#add_version)
 * [doc_version](#doc_version)
 * [endpoint_auth_wrapper](#endpoint_auth_wrapper)
@@ -248,6 +249,13 @@ add_swagger_documentation \
    add_base_path: true # only if base_path given
 ```
 
+#### add_root: <a name="add_root"></a>
+Add root element to all the responses, default is: `false`.
+```ruby
+add_swagger_documentation \
+   add_root: true
+```
+
 #### add_version: <a name="add_version"></a>
 
 Add `version` key to the documented path keys, default is: `true`,
@@ -447,6 +455,7 @@ add_swagger_documentation \
 * [Extensions](#extensions)
 * [Response examples documentation](#response-examples)
 * [Response headers documentation](#response-headers)
+* [Adding root element to responses](#response-root)
 
 #### Swagger Header Parameters  <a name="headers"></a>
 
@@ -913,7 +922,7 @@ desc 'Attach a field to an entity through a PUT',
     failure: [
       { code: 400, message: 'Bad request' },
       { code: 404, message: 'Not found' }
-    ]  
+    ]
 put do
   # your code comes here
 end
@@ -1180,6 +1189,60 @@ The result will look like following:
 
 Failure information can be passed as an array of arrays or an array of hashes.
 
+#### Adding root element to responses <a name="response-root"></a>
+
+You can specify a custom root element for a successful response:
+
+```ruby
+route_setting :swagger, root: 'cute_kitten'
+desc 'Get a kitten' do
+  http_codes [{ code: 200, model: Entities::Kitten }]
+end
+get '/kittens/:id' do
+end
+```
+
+The result will look like following:
+
+```
+  "responses": {
+    "200": {
+      "description": "Get a kitten",
+      "schema": {
+        "type": "object",
+        "properties": { "cute_kitten": { "$ref": "#/definitions/Kitten" } }
+      }
+    }
+  }
+```
+
+If you specify `true`, the value of the root element will be deduced based on the model name.
+E.g. in the following example the root element will be "kittens":
+
+```ruby
+route_setting :swagger, root: true
+desc 'Get kittens' do
+  is_array true
+  http_codes [{ code: 200, model: Entities::Kitten }]
+end
+get '/kittens' do
+end
+```
+
+The result will look like following:
+
+```
+  "responses": {
+    "200": {
+      "description": "Get kittens",
+      "schema": {
+        "type": "object",
+        "properties": { "type": "array", "items": { "kittens": { "$ref": "#/definitions/Kitten" } } }
+      }
+    }
+  }
+```
+
 ## Using Grape Entities <a name="grape-entity"></a>
 
 Add the [grape-entity](https://github.com/ruby-grape/grape-entity) and [grape-swagger-entity](https://github.com/ruby-grape/grape-swagger-entity) gem to your Gemfile.

lib/grape-swagger/doc_methods.rb

@@ -103,6 +103,7 @@ def defaults
         base_path: nil,
         add_base_path: false,
         add_version: true,
+        add_root: false,
         hide_documentation_path: true,
         format: :json,
         authorizations: nil,

lib/grape-swagger/endpoint.rb

@@ -120,7 +120,7 @@ def method_object(route, options, path)
       method[:consumes]    = consumes_object(route, options[:format])
       method[:parameters]  = params_object(route, options, path)
       method[:security]    = security_object(route)
-      method[:responses]   = response_object(route)
+      method[:responses]   = response_object(route, options)
       method[:tags]        = route.options.fetch(:tags, tag_object(route, path))
       method[:operationId] = GrapeSwagger::DocMethods::OperationId.build(route, path)
       method[:deprecated] = deprecated_object(route)
@@ -195,7 +195,7 @@ def params_object(route, options, path)
       parameters.presence
     end
 
-    def response_object(route)
+    def response_object(route, options)
       codes = http_codes_from_route(route)
       codes.map! { |x| x.is_a?(Array) ? { code: x[0], message: x[1], model: x[2], examples: x[3], headers: x[4] } : x }
 
@@ -220,7 +220,7 @@ def response_object(route)
 
         @definitions[response_model][:description] = description_object(route)
 
-        memo[value[:code]][:schema] = build_reference(route, value, response_model)
+        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
         memo[value[:code]][:examples] = value[:examples] if value[:examples]
       end
     end
@@ -261,10 +261,27 @@ def tag_object(route, path)
 
     private
 
-    def build_reference(route, value, response_model)
+    def build_reference(route, value, response_model, settings)
       # TODO: proof that the definition exist, if model isn't specified
       reference = { '$ref' => "#/definitions/#{response_model}" }
-      route.options[:is_array] && value[:code] < 300 ? { type: 'array', items: reference } : reference
+      return reference unless value[:code] < 300
+
+      reference = { type: 'array', items: reference } if route.options[:is_array]
+      build_root(route, reference, response_model, settings)
+    end
+
+    def build_root(route, reference, response_model, settings)
+      default_root = route.options[:is_array] ? response_model.downcase.pluralize : response_model.downcase
+      case route.settings.dig(:swagger, :root)
+      when true
+        { type: 'object', properties: { default_root => reference } }
+      when false
+        reference
+      when nil
+        settings[:add_root] ? { type: 'object', properties: { default_root => reference } } : reference
+      else
+        { type: 'object', properties: { route.settings.dig(:swagger, :root) => reference } }
+      end
     end
 
     def file_response?(value)

spec/swagger_v2/api_swagger_v2_response_with_root_spec.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'response with root' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  before :all do
+    module TheApi
+      class ResponseApiWithRoot < Grape::API
+        format :json
+
+        desc 'This returns something',
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/ordinary_response' do
+          { 'declared_params' => declared(params) }
+        end
+
+        desc 'This returns something',
+             is_array: true,
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_array' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :swagger, root: true
+        desc 'This returns something',
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_root' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :swagger, root: true
+        desc 'This returns something',
+             is_array: true,
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_array_and_root' do
+          { 'declared_params' => declared(params) }
+        end
+
+        route_setting :swagger, root: 'custom_root'
+        desc 'This returns something',
+             http_codes: [{ code: 200, model: Entities::Something }]
+        get '/response_with_custom_root' do
+          { 'declared_params' => declared(params) }
+        end
+
+        add_swagger_documentation
+      end
+    end
+  end
+
+  def app
+    TheApi::ResponseApiWithRoot
+  end
+
+  describe 'GET /ordinary_response' do
+    subject do
+      get '/swagger_doc/ordinary_response'
+      JSON.parse(last_response.body)
+    end
+
+    it 'does not add root or array' do
+      schema = subject.dig('paths', '/ordinary_response', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        '$ref' => '#/definitions/Something'
+      )
+    end
+  end
+
+  describe 'GET /response_with_array' do
+    subject do
+      get '/swagger_doc/response_with_array'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds array to the response' do
+      schema = subject.dig('paths', '/response_with_array', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'array', 'items' => { '$ref' => '#/definitions/Something' }
+      )
+    end
+  end
+
+  describe 'GET /response_with_root' do
+    subject do
+      get '/swagger_doc/response_with_root'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds root to the response' do
+      schema = subject.dig('paths', '/response_with_root', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'object',
+        'properties' => { 'something' => { '$ref' => '#/definitions/Something' } }
+      )
+    end
+  end
+
+  describe 'GET /response_with_array_and_root' do
+    subject do
+      get '/swagger_doc/response_with_array_and_root'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds root and array to the response' do
+      schema = subject.dig('paths', '/response_with_array_and_root', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'object',
+        'properties' => {
+          'somethings' => { 'type' => 'array', 'items' => { '$ref' => '#/definitions/Something' } }
+        }
+      )
+    end
+  end
+
+  describe 'GET /response_with_custom_root' do
+    subject do
+      get '/swagger_doc/response_with_custom_root'
+      JSON.parse(last_response.body)
+    end
+
+    it 'adds root to the response' do
+      schema = subject.dig('paths', '/response_with_custom_root', 'get', 'responses', '200', 'schema')
+      expect(schema).to eq(
+        'type' => 'object',
+        'properties' => { 'custom_root' => { '$ref' => '#/definitions/Something' } }
+      )
+    end
+  end
+end