adding ability to describe responses as reference objects in the swagger

lib/apipie/configuration.rb

@@ -11,13 +11,14 @@ class Configuration
       :persist_show_in_doc, :authorize,
       :swagger_include_warning_tags, :swagger_content_type_input, :swagger_json_input_uses_refs,
       :swagger_suppress_warnings, :swagger_api_host, :swagger_generate_x_computed_id_field,
-      :swagger_allow_additional_properties_in_response
+      :swagger_allow_additional_properties_in_response, :swagger_responses_use_refs
 
     alias_method :validate?, :validate
     alias_method :required_by_default?, :required_by_default
     alias_method :namespaced_resources?, :namespaced_resources
     alias_method :swagger_include_warning_tags?, :swagger_include_warning_tags
     alias_method :swagger_json_input_uses_refs?, :swagger_json_input_uses_refs
+    alias_method :swagger_responses_use_refs?, :swagger_responses_use_refs
     alias_method :swagger_generate_x_computed_id_field?, :swagger_generate_x_computed_id_field
 
     # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
@@ -179,6 +180,7 @@ def initialize
       @swagger_api_host = "localhost:3000"
       @swagger_generate_x_computed_id_field = false
       @swagger_allow_additional_properties_in_response = false
+      @swagger_responses_use_refs = true
     end
   end
 end

lib/apipie/response_description.rb

@@ -5,13 +5,14 @@ class ResponseObject
       include Apipie::DSL::Base
       include Apipie::DSL::Param
 
-      attr_accessor :additional_properties
+      attr_accessor :additional_properties, :typename
 
-      def initialize(method_description, scope, block)
+      def initialize(method_description, scope, block, typename)
         @method_description = method_description
         @scope = scope
         @param_group = {scope: scope}
         @additional_properties = false
+        @typename = typename
 
         self.instance_exec(&block) if block
 
@@ -67,6 +68,11 @@ def is_array?
       @is_array_of != false
     end
 
+    def typename
+      @response_object.typename
+    end
+
+
     def initialize(method_description, code, options, scope, block, adapter)
 
       @type_ref = options[:param_group]
@@ -93,7 +99,7 @@ def initialize(method_description, code, options, scope, block, adapter)
       if adapter
         @response_object = adapter
       else
-        @response_object = ResponseObject.new(method_description, scope, block)
+        @response_object = ResponseObject.new(method_description, scope, block, @type_ref)
       end
 
       @response_object.additional_properties ||= options[:additional_properties]

lib/apipie/response_description_adapter.rb

@@ -147,18 +147,19 @@ def validator
   class ResponseDescriptionAdapter
 
     def self.from_self_describing_class(cls)
-      adapter = ResponseDescriptionAdapter.new
+      adapter = ResponseDescriptionAdapter.new(cls.to_s)
       props = cls.describe_own_properties
       adapter.add_property_descriptions(props)
       adapter
     end
 
-    def initialize
+    def initialize(typename)
       @property_descs = []
       @additional_properties = false
+      @typename = typename
     end
 
-    attr_accessor :additional_properties
+    attr_accessor :additional_properties, :typename
 
     def allow_additional_properties
       additional_properties

lib/apipie/swagger_generator.rb

@@ -24,6 +24,10 @@ def params_in_body_use_reference?
       Apipie.configuration.swagger_json_input_uses_refs
     end
 
+    def responses_use_reference?
+      Apipie.configuration.swagger_responses_use_refs?
+    end
+
     def include_warning_tags?
       Apipie.configuration.swagger_include_warning_tags
     end
@@ -259,6 +263,10 @@ def swagger_op_id_for_method(method)
       remove_colons method.resource.controller.name + "::" + method.method
     end
 
+    def swagger_id_for_typename(typename)
+      typename
+    end
+
     def swagger_op_id_for_path(http_method, path)
       # using lowercase http method, because the 'swagger-codegen' tool outputs
       # strange method names if the http method is in uppercase
@@ -339,7 +347,13 @@ def response_schema(response)
         # no need to warn about "missing default value for optional param" when processing response definitions
         prev_value = @disable_default_value_warning
         @disable_default_value_warning = true
-        schema = json_schema_obj_from_params_array(response.params_ordered)
+
+        if responses_use_reference? && response.typename
+          schema = {"$ref" => gen_referenced_block_from_params_array(swagger_id_for_typename(response.typename), response.params_ordered, allow_nulls)}
+        else
+          schema = json_schema_obj_from_params_array(response.params_ordered, allow_nulls)
+        end
+
       ensure
         @disable_default_value_warning = prev_value
       end
@@ -498,10 +512,10 @@ def json_schema_obj_from_params_array(params_array)
       param_defs.length > 0 ? result : nil
     end
 
-    def gen_referenced_block_from_params_array(name, params_array)
+    def gen_referenced_block_from_params_array(name, params_array, allow_nulls=false)
       return ref_to(:name) if @definitions.key(:name)
 
-      schema_obj = json_schema_obj_from_params_array(params_array)
+      schema_obj = json_schema_obj_from_params_array(params_array, allow_nulls)
       return nil if schema_obj.nil?
 
       @definitions[name.to_sym] = schema_obj