Add Support for default response. (#868)

* Add Support for default response.

support default as a response code as specified in https://swagger.io/docs/specification/2-0/describing-responses/ Default Response section.

* add docs

Author: dhruvCW

CHANGELOG.md

@@ -3,6 +3,7 @@
 #### Features
 
 * [#872](https://github.com/ruby-grape/grape-swagger/pull/872): Add `consumes` and `produces` options to `add_swagger_documentation` - [@spaceraccoon](https://github.com/spaceraccoon)
+* [#868](https://github.com/ruby-grape/grape-swagger/pull/868): Add `default` endpoint option to specify default response - [@dhruvCW](https://github.com/dhruvCW)
 * Your contribution here.
 
 #### Fixes

README.md

@@ -1042,6 +1042,50 @@ end
 }
 ```
 
+#### Default response <a name="default-response"></a>
+
+By setting the `default` option you can also define a default response that is the result returned for all unspecified status codes.
+The definition supports the same syntax as `success` or `failure`.
+
+In the following cases, the schema ref would be taken from route.
+
+```ruby
+desc 'thing', default: { message: 'the default response' }
+get '/thing' do
+  # ...
+end
+```
+The generated swagger section will be something like
+
+```json
+"responses": {
+  "default": {
+    "description": "the default response"
+  }
+},
+```
+Just like with `success` or `failure` you can also provide a `model` parameter.
+
+```ruby
+desc 'Get a list of stuff',
+    default: { model: Entities::UseResponse, message: 'the default response' }
+get do
+  # your code comes here
+end
+```
+The generated swagger document will then correctly reference the model schema.
+
+```json
+"responses": {
+  "default": {
+    "description": "the default response",
+    "schema": {
+      "$ref": "#/definitions/UseResponse"
+    }
+  }
+},
+```
+
 
 #### Extensions <a name="extensions"></a>
 

lib/grape-swagger/endpoint.rb

@@ -5,7 +5,7 @@
 require 'grape-swagger/endpoint/params_parser'
 
 module Grape
-  class Endpoint
+  class Endpoint # rubocop:disable Metrics/ClassLength
     def content_types_for(target_class)
       content_types = (target_class.content_types || {}).values
 
@@ -241,7 +241,8 @@ def http_codes_from_route(route)
       if route.http_codes.is_a?(Array) && route.http_codes.any? { |code| success_code?(code) }
         route.http_codes.clone
       else
-        success_codes_from_route(route) + (route.http_codes || route.options[:failure] || [])
+        success_codes_from_route(route) + default_code_from_route(route) +
+          (route.http_codes || route.options[:failure] || [])
       end
     end
 
@@ -268,6 +269,21 @@ def tag_object(route, path)
 
     private
 
+    def default_code_from_route(route)
+      entity = route.options[:default_response]
+      return [] if entity.nil?
+
+      default_code = { code: 'default', message: 'Default Response' }
+      if entity.is_a?(Hash)
+        default_code[:message] = entity[:message] || default_code[:message]
+        default_code[:model] = entity[:model] if entity[:model].present?
+      else
+        default_code[:model] = entity
+      end
+
+      [default_code]
+    end
+
     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))
@@ -295,7 +311,7 @@ def build_reference(route, value, response_model, settings)
                   else
                     build_reference_hash(response_model)
                   end
-      return reference unless value[:code] < 300
+      return reference unless value[:code] == 'default' || value[:code] < 300
 
       if value.key?(:as) && value.key?(:is_array)
         reference[value[:as]] = build_reference_array(reference[value[:as]])

spec/swagger_v2/api_swagger_v2_response_with_models_spec.rb

@@ -15,7 +15,8 @@ class ResponseApiModels < Grape::API
              failure: [
                { code: 400, message: 'NotFound', model: '' },
                { code: 404, message: 'BadRequest', model: Entities::ApiError }
-             ]
+             ],
+             default_response: { message: 'Error', model: Entities::ApiError }
         get '/use-response' do
           { 'declared_params' => declared(params) }
         end
@@ -42,7 +43,8 @@ def app
         'responses' => {
           '200' => { 'description' => 'This returns something', 'schema' => { '$ref' => '#/definitions/UseResponse' } },
           '400' => { 'description' => 'NotFound' },
-          '404' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' } }
+          '404' => { 'description' => 'BadRequest', 'schema' => { '$ref' => '#/definitions/ApiError' } },
+          'default' => { 'description' => 'Error', 'schema' => { '$ref' => '#/definitions/ApiError' } }
         },
         'tags' => ['use-response'],
         'operationId' => 'getUseResponse'