Allow multiple success responses (#747)

* Allow multiple success responses - Issue# 674

* Adding documentation in README for multiple values in success for response

* Making a slight change in the documentation

Author: charanpanchagnula

CHANGELOG.md

@@ -7,6 +7,7 @@
 #### Fixes
 
 * Your contribution here.
+* [#747](https://github.com/ruby-grape/grape-swagger/pull/747): Allow multiple different success responses - [@charanftp3](https://github.com/charanpanchagnula).
 * [#746](https://github.com/ruby-grape/grape-swagger/pull/746): Fix path with optional format - [@fnordfish](https://github.com/fnordfish).
 * [#743](https://github.com/ruby-grape/grape-swagger/pull/743): CI: use 2.4.6, 2.5.5 - [@olleolleolle](https://github.com/olleolleolle).
 * [#737](https://github.com/ruby-grape/grape-swagger/pull/737): Add swagger endpoint guard to both doc endpoints - [@urkle](https://github.com/urkle).

README.md

@@ -900,6 +900,45 @@ end
 },
 ```
 
+#### Multiple status codes for response <a name="multiple-status-response"></a>
+
+Multiple values can be provided for `success` and `failure` attributes in the response.
+
+```ruby
+desc 'Attach a field to an entity through a PUT',
+    success: [
+      { code: 201, model: Entities::UseResponse, message: 'Successfully created' },
+      { code: 204, message: 'Already exists' }
+    ],
+    failure: [
+      { code: 400, message: 'Bad request' },
+      { code: 404, message: 'Not found' }
+    ]  
+put do
+  # your code comes here
+end
+```
+
+```json
+"responses": {
+  "201": {
+    "description": "Successfully created",
+    "schema": {
+      "$ref": "#/definitions/UseResponse"
+    }
+  },
+  "204": {
+    "description": "Already exists"
+  },
+  "400": {
+    "description": "Bad request"
+  },
+  "404": {
+    "description": "Not found"
+  }
+},
+```
+
 
 #### File response <a name="file-response"></a>
 

lib/grape-swagger/endpoint.rb

@@ -238,20 +238,13 @@ def http_codes_from_route(route)
     end
 
     def success_codes_from_route(route)
-      default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
-      if @entity.is_a?(Hash)
-        default_code[:code] = @entity[:code] if @entity[:code].present?
-        default_code[:model] = @entity[:model] if @entity[:model].present?
-        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]
-      else
-        default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
-        default_code[:model] = @entity if @entity
-        default_code[:message] = route.description || default_code[:message].sub('{item}', @item)
+      if @entity.is_a?(Array)
+        return @entity.map do |entity|
+          success_code_from_entity(route, entity)
+        end
       end
 
-      [default_code]
+      [success_code_from_entity(route, @entity)]
     end
 
     def tag_object(route, path)
@@ -350,5 +343,22 @@ def hidden?(route, options)
 
       options[:token_owner] ? route_hidden.call(send(options[:token_owner].to_sym)) : route_hidden.call
     end
+
+    def success_code_from_entity(route, entity)
+      default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
+      if entity.is_a?(Hash)
+        default_code[:code] = entity[:code] if entity[:code].present?
+        default_code[:model] = entity[:model] if entity[:model].present?
+        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]
+      else
+        default_code = GrapeSwagger::DocMethods::StatusCodes.get[route.request_method.downcase.to_sym]
+        default_code[:model] = entity if entity
+        default_code[:message] = route.description || default_code[:message].sub('{item}', @item)
+      end
+
+      default_code
+    end
   end
 end

spec/swagger_v2/api_swagger_v2_response_spec.rb

@@ -31,6 +31,17 @@ class ResponseApi < Grape::API
           { 'declared_params' => declared(params) }
         end
 
+        desc 'This returns something',
+             success: [
+               { code: 200, message: 'Request has succeeded' },
+               { code: 201, message: 'Successful Operation' },
+               { code: 204, message: 'Request was fulfilled' }
+             ],
+             failure: [{ code: 400, message: 'NotFound', model: Entities::ApiError }]
+        get '/multiple-success-responses' do
+          { 'declared_params' => declared(params) }
+        end
+
         add_swagger_documentation
       end
     end
@@ -106,4 +117,27 @@ def app
       expect(subject['definitions']).to eql(swagger_params_as_response_object)
     end
   end
+
+  describe 'uses params as response object when response contains multiple values for success' do
+    subject do
+      get '/swagger_doc/multiple-success-responses'
+      JSON.parse(last_response.body)
+    end
+
+    specify do
+      expect(subject['paths']['/multiple-success-responses']['get']).to eql(
+        'description' => 'This returns something',
+        'produces' => ['application/json'],
+        'responses' => {
+          '200' => { 'description' => 'Request has succeeded' },
+          '201' => { 'description' => 'Successful Operation' },
+          '204' => { 'description' => 'Request was fulfilled' },
+          '400' => { 'description' => 'NotFound', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+        },
+        'tags' => ['multiple-success-responses'],
+        'operationId' => 'getMultipleSuccessResponses'
+      )
+      expect(subject['definitions']).to eql(swagger_params_as_response_object)
+    end
+  end
 end