handle multiple presents (#813)

* handle multiple presents

* update documentation and changelog

Author: AntoineGst

.rubocop.yml

@@ -54,7 +54,7 @@ Metrics/BlockLength:
     - spec/**/*
 
 Metrics/ClassLength:
-  Max: 300
+  Max: 350
 
 Metrics/CyclomaticComplexity:
   Max: 17

.rubocop_todo.yml

@@ -28,7 +28,7 @@ Metrics/MethodLength:
 
 # Offense count: 7
 Metrics/PerceivedComplexity:
-  Max: 14
+  Max: 16
 
 # Offense count: 3
 Style/ClassVars:

CHANGELOG.md

@@ -3,6 +3,7 @@
 #### Features
 
 * Your contribution here.
+* [#813](https://github.com/ruby-grape/grape-swagger/pull/813): Handle multiple presents - [@AntoineGuestin](https://github.com/AntoineGuestin).
 
 #### Fixes
 

README.md

@@ -458,6 +458,7 @@ add_swagger_documentation \
 * [Response examples documentation](#response-examples)
 * [Response headers documentation](#response-headers)
 * [Adding root element to responses](#response-root)
+* [Multiple present Response](#multiple-response)
 
 #### Swagger Header Parameters  <a name="headers"></a>
 
@@ -1262,6 +1263,75 @@ The result will look like following:
     }
   }
 ```
+#### Multiple present Response <a name="multiple-response"></a>
+
+You can specify a custom multiple response by using the `as` key:
+```ruby
+desc 'Multiple response',
+  success: [
+    { model: Entities::EnumValues, as: :gender },
+    { model: Entities::Something, as: :somethings }
+  ]
+end
+
+get '/things' do
+  ...
+end
+```
+The result will look like following:
+```
+  "responses": {
+    "200": {
+      "description": "Multiple response",
+      "schema":{
+        "type":"object",
+        "properties":{
+          "gender":{
+            "$ref":"#/definitions/EnumValues"
+          },
+          "somethings":{
+            "$ref":"#/definitions/Something"
+          }
+        }
+      }
+    }
+  }
+```
+You can also specify if the response is an array, with the `is_array` key:
+```ruby
+desc 'Multiple response with array',
+  success: [
+    { model: Entities::EnumValues, as: :gender },
+    { model: Entities::Something, as: :somethings, is_array: true }
+  ]
+end
+
+get '/things' do
+  ...
+end
+```
+The result will look like following:
+```
+  "responses": {
+    "200": {
+      "description": "Multiple response with array",
+      "schema":{
+        "type":"object",
+        "properties":{
+          "gender":{
+            "$ref":"#/definitions/EnumValues"
+          },
+          "somethings":{
+            "type":"array",
+            "items":{
+                "$ref":"#/definitions/Something"
+            }
+          }
+        }
+      }
+    }
+  }
+```
 
 ## Using Grape Entities <a name="grape-entity"></a>
 

lib/grape-swagger/endpoint.rb

@@ -201,8 +201,7 @@ def params_object(route, options, path)
     def response_object(route, options)
       codes(route).each_with_object({}) do |value, memo|
         value[:message] ||= ''
-        memo[value[:code]] = { description: value[:message] }
-
+        memo[value[:code]] = { description: value[:message] ||= '' } unless memo[value[:code]].present?
         memo[value[:code]][:headers] = value[:headers] if value[:headers]
 
         next build_file_response(memo[value[:code]]) if file_response?(value[:model])
@@ -221,7 +220,7 @@ def response_object(route, options)
         next if response_model.start_with?('Swagger_doc')
 
         @definitions[response_model][:description] ||= "#{response_model} model"
-        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
+        build_memo_schema(memo, route, value, response_model, options)
         memo[value[:code]][:examples] = value[:examples] if value[:examples]
       end
     end
@@ -268,15 +267,45 @@ def tag_object(route, path)
 
     private
 
+    def build_memo_schema(memo, route, value, response_model, options)
+      if memo[value[:code]][:schema] && value[:as]
+        memo[value[:code]][:schema][:properties].merge!(build_reference(route, value, response_model, options))
+      elsif value[:as]
+        memo[value[:code]][:schema] = {
+          type: :object,
+          properties: build_reference(route, value, response_model, options)
+        }
+      else
+        memo[value[:code]][:schema] = build_reference(route, value, response_model, options)
+      end
+    end
+
     def build_reference(route, value, response_model, settings)
       # TODO: proof that the definition exist, if model isn't specified
-      reference = { '$ref' => "#/definitions/#{response_model}" }
+      reference = if value.key?(:as)
+                    { value[:as] => build_reference_hash(response_model) }
+                  else
+                    build_reference_hash(response_model)
+                  end
       return reference unless value[:code] < 300
 
-      reference = { type: 'array', items: reference } if route.options[:is_array]
+      if value.key?(:as) && value.key?(:is_array)
+        reference[value[:as]] = build_reference_array(reference[value[:as]])
+      elsif route.options[:is_array]
+        reference = build_reference_array(reference)
+      end
+
       build_root(route, reference, response_model, settings)
     end
 
+    def build_reference_hash(response_model)
+      { '$ref' => "#/definitions/#{response_model}" }
+    end
+
+    def build_reference_array(reference)
+      { type: 'array', items: reference }
+    end
+
     def build_root(route, reference, response_model, settings)
       default_root = response_model.underscore
       default_root = default_root.pluralize if route.options[:is_array]
@@ -382,6 +411,8 @@ def success_code_from_entity(route, entity)
         default_code[:message] = entity[:message] || route.description || default_code[:message].sub('{item}', @item)
         default_code[:examples] = entity[:examples] if entity[:examples]
         default_code[:headers] = entity[:headers] if entity[:headers]
+        default_code[:as] = entity[:as] if entity[:as]
+        default_code[:is_array] = entity[:is_array] if entity[:is_array]
       else
         default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
         default_code[:model] = entity if entity

spec/issues/776_multiple_presents_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe '#776 multiple presents spec' do
+  include_context "#{MODEL_PARSER} swagger example"
+
+  let(:app) do
+    Class.new(Grape::API) do
+      namespace :issue_776 do
+        desc 'Get multiple presents',
+             success: [
+               { model: Entities::EnumValues, as: :gender },
+               { model: Entities::Something, as: :somethings, is_array: true }
+             ]
+
+        get do
+          present :gender, { number: 1, gender: 'Male' }, with: Entities::EnumValues
+          present :somethings, [
+            { id: 1, text: 'element_1', links: %w[link1 link2] },
+            { id: 2, text: 'element_2', links: %w[link1 link2] }
+          ], with: Entities::Something, is_array: true
+        end
+      end
+
+      add_swagger_documentation format: :json
+    end
+  end
+
+  subject do
+    get '/swagger_doc'
+    JSON.parse(last_response.body)
+  end
+
+  let(:definitions) { subject['definitions'] }
+  let(:schema) { subject['paths']['/issue_776']['get']['responses']['200']['schema'] }
+
+  specify { expect(definitions.keys).to include 'EnumValues', 'Something' }
+
+  specify do
+    expect(schema).to eql({
+      'properties' => {
+        'somethings' => {
+          'items' => {
+            '$ref' => '#/definitions/Something'
+          },
+          'type' => 'array'
+        },
+        'gender' => {
+          '$ref' => '#/definitions/EnumValues'
+        }
+      },
+      'type' => 'object'
+    })
+  end
+end