apipie-rails 0.5.7 → 0.5.8

data/spec/dummy/app/controllers/pets_using_auto_views_controller.rb

@@ -0,0 +1,73 @@
+#
+# demonstration of how the 'describe_own_properties' method can be used
+# to integrate Apipie response descriptions with view generation packages
+# such as, for example, Grape::Entity
+#
+
+# Consider a hypothetical SelfDocumentingView class (a stand-in for Grape::Entity
+# for demonstrational purposes). This is an abstract class, supporting the implementation
+# of actual views as subclasses of SelfDocumentingView.
+#
+# A user of SelfDocumentingView would implement a subclass for each desired view.  Each such
+# view definition would include, for each field that should be returned in the JSON response,
+# an instance method called v_<name>__<type>.
+#
+# SelfDocumentingView would then scan the subclass for such fields and:
+# 1. Given an id:  fetch the matching model and generated a view from it using the field definitions
+# 2. Describe the structure of such views to Apipie using self.describe_own_properties
+#
+# (see the controller implementation below for how such a class might be used)
+
+class SelfDocumentingView
+  # self.describe_own_properties (a class method) generates the meta-data
+  # (i.e., the type description) for the subclass.
+  def self.describe_own_properties
+    (self.instance_methods - self.class.instance_methods).map{|m|
+      if matchdata = /^v_(\w+)__(\w+)$/.match(m)
+        Apipie::prop(matchdata[1], matchdata[2])
+      end
+    }.compact
+  end
+
+  # to_json (an instance method) generates the actual view
+  def to_json
+    { note: "in an actual implementation of SelfDocumentingView, this method
+             would call each v_<name>__<type> method and include its output
+             in the response as a (<name>: <value>) pair"
+    }
+  end
+
+  def initialize(id)
+    load_from_model(id)
+  end
+
+  def load_from_model(id)
+    # in a real implementation of SelfDocumentingView, this
+    # method would load the fields to be displayed from the model
+    # instance identified by 'id'
+  end
+end
+
+
+#
+# ViewOfPet extends SelfDocumentingView to include specific fields
+#
+class ViewOfPet < SelfDocumentingView
+  attr_accessor :v_pet_name__string
+  attr_accessor :v_animal_type__string
+  attr_accessor :v_age__number
+end
+
+
+class PetsUsingAutoViewsController < ApplicationController
+  #-----------------------------------------------------------
+  # Method returning an array of AutomatedViewOfPet (where
+  # AutomatedViewOfPet is an auto-generated self-describing class)
+  # -----------------------------------------------------------
+  api :GET, "/pet_described_using_automated_view/:id", "Get the measurements of a single pet"
+  param :id, String
+  returns ViewOfPet, :desc => "like Pet, but different"
+  def pet_described_using_automated_view
+    render :plain => ViewOfPet.new(params.id).to_json
+  end
+end

data/spec/dummy/app/controllers/pets_using_self_describing_classes_controller.rb

@@ -0,0 +1,95 @@
+#----------------------------------------------------------------------------------------------------
+# A "self-describing class" is a class that respond_to? :describe_own_properties
+# and returns an array of Property Descriptions.
+# (The simple way to create Property Description objects is using the Apipie::prop helper function,
+# which is a factory for Apipie::ResponseDescriptionAdapter::PropDesc instances)
+#
+#----------------------------------------------------------------------------------------------------
+
+
+# in this example, Pet is a self-describing class with only two properties.
+# In a real implementation, the Pet class would actually do something with these properties.
+# Here, the class is defined to only include the describe_own_properties method.
+class Pet
+  def self.describe_own_properties
+    [
+        Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
+        Apipie::prop(:animal_type, 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
+        Apipie::additional_properties(false)
+    ]
+  end
+end
+
+#
+# PetWithMeasurements is a self-describing class with an embedded object
+#
+class PetWithMeasurements
+  def self.describe_own_properties
+    [
+        Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
+        Apipie::prop('animal_type', 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
+        Apipie::prop(:pet_measurements, 'object', {}, [
+            Apipie::prop(:weight, 'number', {:description => "Weight in pounds" }),
+            Apipie::prop(:height, 'number', {:description => "Height in inches" }),
+            Apipie::prop(:num_legs, 'number', {:description => "Number of legs", :required => false }),
+            Apipie::additional_properties(false)
+        ])
+    ]
+  end
+end
+
+#
+# PetWithManyMeasurements is a self-describing class with an embedded object
+#
+class PetWithManyMeasurements
+  def self.describe_own_properties
+    [
+        Apipie::prop(:pet_name, 'string', {:description => 'Name of pet', :required => false}),
+        Apipie::prop(:many_pet_measurements, 'object', {is_array: true}, [
+            Apipie::prop(:weight, 'number', {:description => "Weight in pounds" }),
+            Apipie::prop(:height, 'number', {:description => "Height in inches" }),
+        ])
+    ]
+  end
+end
+
+
+
+class PetsUsingSelfDescribingClassesController < ApplicationController
+  resource_description do
+    description 'A controller to test "returns" using self-describing classes'
+    short 'Pets'
+    path '/pets2'
+  end
+
+  #-----------------------------------------------------------
+  # Method returning an array of Pet (a self-describing class)
+  # -----------------------------------------------------------
+  api :GET, "/pets_described_as_class", "Get all pets"
+  returns :array_of => Pet, :desc => "list of pets"
+  def pets_described_as_class
+    render :plain => "all pets"
+  end
+
+  #-----------------------------------------------------------
+  # Method returning an array of PetWithMeasurements (a self-describing class)
+  # -----------------------------------------------------------
+  api :GET, "/pets_with_measurements_described_as_class/:id", "Get the measurements of a single pet"
+  param :id, String
+  returns PetWithMeasurements, :desc => "measurements of the pet"
+  def pets_with_measurements_described_as_class
+    render :plain => "all pets"
+  end
+
+  #-----------------------------------------------------------
+  # Method returning an array of PetWithManyMeasurements (a self-describing class with array field)
+  # -----------------------------------------------------------
+  api :GET, "/pets_with_many_measurements_as_class/:id", "Get the measurements of a single pet"
+  param :id, String
+  returns PetWithManyMeasurements, :desc => "measurements of the pet"
+  def pets_with_many_measurements_as_class
+    render :plain => "all pets"
+  end
+
+end
+

data/spec/lib/extractor/writer_spec.rb

@@ -57,10 +57,38 @@ describe Apipie::Extractor::Writer do
     }
   }
 
-  describe "with doc_path overriden in configuration" do
-    it "should use the doc_path specified in configuration" do
-      Apipie.configuration.doc_path = "user_specified_doc_path"
-      expect(writer_class.examples_file).to eql(File.join(Rails.root, "user_specified_doc_path", "apipie_examples.json"))
+  context 'with doc_path overriden in configuration' do
+    around(:each) do |example|
+      standard_path = Apipie.configuration.doc_path
+      Apipie.configuration.doc_path = 'user_specified_doc_path'
+      example.run
+      Apipie.configuration.doc_path = standard_path
+    end
+
+    it 'should use the doc_path specified in configuration' do
+      expect(writer_class.examples_file).to eql(File.join(Rails.root, 'user_specified_doc_path', 'apipie_examples.json'))
+    end
+  end
+
+  context 'when compressing examples' do
+    around(:each) do |example|
+      Apipie.configuration.compress_examples = true
+      example.run
+      FileUtils.rm(writer_class.examples_file) if File.exist?(writer_class.examples_file)
+      Apipie.configuration.compress_examples = nil
+    end
+
+    it 'should write to a compressed file' do
+      expect(writer_class.examples_file).to match(/\.gz$/)
+      writer_class.write_recorded_examples(records)
+      expect(File.exist?(writer_class.examples_file))
+    end
+
+    it 'should read from a compressed file' do
+      writer_class.write_recorded_examples(records)
+      expected_string = writer_class.send(:serialize_examples, records)
+      expect(writer_class.load_recorded_examples)
+        .to eql(writer_class.send(:deserialize_examples, expected_string))
     end
   end
 

data/spec/lib/method_description_spec.rb

@@ -68,4 +68,31 @@ describe Apipie::MethodDescription do
 
   end
 
+  describe "response-only properties" do
+    before(:each) do
+      @resource = Apipie::ResourceDescription.new(ApplicationController, "dummy")
+      dsl_data[:params] = [[:a, String, nil, {:only_in => :request}, nil],
+                           [:b, String, nil, {:only_in => :response}, nil],
+                           [:c, String, nil, {}, nil]]
+      @method = Apipie::MethodDescription.new(:a, @resource, dsl_data)
+      @resource.add_method_description @method
+    end
+
+    it "should ignore response-only parameters" do
+      expect(@method.params.keys).to eq([:a, :c])
+      expect(@method.to_json[:params].map{|h| h[:name]}).to eq(['a', 'c'])
+    end
+  end
+
+
+  describe "'returns' properties" do
+    it "should raise an error if both :param_group and :array_of are specified in 'returns'" do
+      @resource = Apipie::ResourceDescription.new(ApplicationController, "dummy")
+      dsl_data[:returns] = { 200 => [{:param_group => 'pet', :array_of => 'pet'}, nil, nil] }
+
+      expect {Apipie::MethodDescription.new(:a, @resource, dsl_data)}.to raise_error(Apipie::ReturnsMultipleDefinitionError)
+    end
+  end
+
+
 end

data/spec/lib/swagger/rake_swagger_spec.rb

@@ -1,6 +1,10 @@
 require 'spec_helper'
 require "json-schema"
 
+require File.expand_path("../../../dummy/app/controllers/twitter_example_controller.rb", __FILE__)
+require File.expand_path("../../../dummy/app/controllers/users_controller.rb", __FILE__)
+require File.expand_path("../../../dummy/app/controllers/pets_controller.rb", __FILE__)
+
 describe 'rake tasks' do
   include_context "rake"
 

data/spec/lib/swagger/swagger_dsl_spec.rb

@@ -0,0 +1,489 @@
+require 'spec_helper'
+require 'rack/utils'
+require 'rspec/expectations'
+
+describe "Swagger Responses" do
+  let(:desc) { Apipie.get_resource_description(controller_class, Apipie.configuration.default_version) }
+
+  let(:swagger) {
+    Apipie.configuration.swagger_suppress_warnings = true
+    Apipie.to_swagger_json(Apipie.configuration.default_version, controller_class.to_s.underscore.sub("_controller", ""))
+  }
+
+  let(:controller_class ) { described_class }
+
+  def swagger_response_for(path, code=200, method='get')
+    swagger[:paths][path][method][:responses][code]
+  end
+
+  def swagger_params_for(path, method='get')
+    swagger[:paths][path][method][:parameters]
+  end
+
+  def swagger_param_by_name(param_name, path, method='get')
+    params = swagger_params_for(path, method)
+    matching = params.select{|p| p[:name] == param_name }
+    raise "multiple params named [#{param_name}] in swagger definition for [#{method } #{path}]" if matching.length > 1
+
+    nil if matching.length == 0
+
+    matching[0]
+  end
+
+
+
+  describe PetsController do
+
+
+    describe "PetsController#index" do
+      subject do
+        desc._methods[:index]
+      end
+
+      it "should return code 200 with array of entries of the format {'pet_name', 'animal_type'}" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(true)
+
+        expect(returns_obj).to match_field_structure([:pet_name, :animal_type])
+      end
+
+      it 'should have the response described in the swagger' do
+        response = swagger_response_for('/pets')
+        expect(response[:description]).to eq("list of pets")
+
+        schema = response[:schema]
+        expect(schema[:type]).to eq("array")
+
+        a_schema = schema[:items]
+        expect(a_schema).to have_field(:pet_name, 'string', {:description => 'Name of pet', :required => false})
+        expect(a_schema).to have_field(:animal_type, 'string', {:description => 'Type of pet', :enum => ['dog','cat','iguana','kangaroo']})
+      end
+
+
+      it "should return code 401 with a String description field" do
+        returns_obj = subject.returns.detect{|e| e.code == 404 }
+
+        expect(returns_obj.code).to eq(404)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:error_message])
+      end
+
+
+      it "should return code 401 with a :reason field (defined in the superclass)" do
+        returns_obj = subject.returns.detect{|e| e.code == 401 }
+
+        expect(returns_obj.code).to eq(401)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:reason])
+      end
+
+      it 'should have the 404 response described in the swagger' do
+        response = swagger_response_for('/pets', 404)
+        expect(response[:description]).to eq("Not Found")
+
+        schema = response[:schema]
+        expect(schema[:type]).to eq("object")
+
+        expect(schema).to have_field(:error_message, 'string', {:description => 'description of the error', :required => true})
+      end
+
+    end
+
+    describe "PetsController#show_as_properties" do
+      subject do
+        desc._methods[:show_as_properties]
+      end
+
+      it "should return code 200 with 'pet_name' and 'animal_type'" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:pet_name, :animal_type])
+      end
+
+      it 'should have the response described in the swagger' do
+        response = swagger_response_for('/pets/{id}/as_properties')
+        expect(response[:description]).to eq("OK")
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:description => 'Name of pet', :required => false})
+        expect(schema).to have_field(:animal_type, 'string', {:description => 'Type of pet', :enum => ['dog','cat','iguana','kangaroo']})
+      end
+
+      it 'should have the 404 response description overridden' do
+        returns_obj = subject.returns.detect{|e| e.code == 404 }
+
+        # puts returns_obj.to_json
+        expect(returns_obj.code).to eq(404)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:another_error_message])
+      end
+    end
+
+    describe "PetsController#show_as_param_group_of_properties" do
+      subject do
+        desc._methods[:show_as_param_group_of_properties]
+      end
+
+      it "should return code 200 with 'pet_name' and 'animal_type'" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:pet_name, :animal_type])
+        expect(returns_obj.params_ordered[0].is_required?).to be_falsey
+        expect(returns_obj.params_ordered[1].is_required?).to be_truthy
+      end
+
+      it 'should have the response described in the swagger' do
+        response = swagger_response_for('/pets/{id}/as_param_group_of_properties')
+        expect(response[:description]).to eq("The pet")
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:description => 'Name of pet', :required => false})
+        expect(schema).to have_field(:animal_type, 'string', {:description => 'Type of pet', :enum => ['dog','cat','iguana','kangaroo']})
+      end
+    end
+
+    describe "PetsController#show_pet_by_id" do
+      subject do
+        desc._methods[:show_pet_by_id]
+      end
+
+      it "should have only oauth (from ApplicationController), common_param (from resource) and pet_id as an input parameters" do
+        params_obj = subject.params_ordered
+
+        expect(params_obj[0].name).to eq(:oauth)
+        expect(params_obj[1].name).to eq(:common_param)
+        expect(params_obj[2].name).to eq(:pet_id)
+      end
+
+      it "should return code 200 with 'pet_id', pet_name' and 'animal_type'" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(false)
+
+        # note that the response is expected NOT to return the parameters marked ':only_in => :request'
+        expect(returns_obj).to match_field_structure([:pet_id, :pet_name, :animal_type])
+      end
+
+      it 'should have the response described in the swagger' do
+        response = swagger_response_for('/pets/pet_by_id')
+        expect(response[:description]).to eq("OK")
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_id, 'number', {:description => 'id of pet'})
+        expect(schema).to have_field(:pet_name, 'string', {:description => 'Name of pet', :required => false})
+        expect(schema).to have_field(:animal_type, 'string', {:description => 'Type of pet', :enum => ['dog','cat','iguana','kangaroo']})
+        expect(schema).not_to have_field(:partial_match_allowed, 'boolean', {:required => false})
+      end
+
+      it "creates a swagger definition with all input parameters" do
+        # a parameter defined for this method
+        expect(swagger_param_by_name(:pet_id, '/pets/pet_by_id')[:type]).to eq('number')
+
+        # a parameter defined for the resource
+        expect(swagger_param_by_name(:common_param, '/pets/pet_by_id')[:type]).to eq('number')
+
+        # a parameter defined in the controller's superclass
+        expect(swagger_param_by_name(:oauth, '/pets/pet_by_id')[:type]).to eq('string')
+      end
+
+    end
+
+    describe "PetsController#get_vote_by_owner_name" do
+      subject do
+        desc._methods[:get_vote_by_owner_name]
+      end
+
+      it "should return code 200 with 'owner_name' and 'vote'" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:owner_name, :vote])
+      end
+
+      it 'should have the response described in the swagger' do
+        response = swagger_response_for('/pets/by_owner_name/did_vote')
+        expect(response[:description]).to eq("OK")
+
+        schema = response[:schema]
+        expect(schema).to have_field(:owner_name, 'string', {:required => false}) # optional because defined using 'param', not 'property'
+        expect(schema).to have_field(:vote, 'boolean')
+      end
+    end
+
+    describe "PetsController#show_extra_info" do
+      subject do
+        desc._methods[:show_extra_info]
+      end
+
+      it "should return code 201 with 'pet_name' and 'animal_type'" do
+        returns_obj = subject.returns.detect{|e| e.code == 201 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(201)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:pet_name, :animal_type])
+      end
+      it 'should have the 201 response described in the swagger' do
+        response = swagger_response_for('/pets/{id}/extra_info', 201)
+        expect(response[:description]).to eq("Found a pet")
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:required => false})
+        expect(schema).to have_field(:animal_type, 'string')
+      end
+
+      it "should return code 202 with spread out 'pet' and encapsulated 'pet_measurements'" do
+        returns_obj = subject.returns.detect{|e| e.code == 202 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(202)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:pet_name,
+                                                      :animal_type,
+                                                      {:pet_measurements => [:weight, :height, :num_legs]}
+                                                     ])
+      end
+      it 'should have the 202 response described in the swagger' do
+        response = swagger_response_for('/pets/{id}/extra_info', 202)
+        expect(response[:description]).to eq('Accepted')
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:required => false})
+        expect(schema).to have_field(:animal_type, 'string')
+        expect(schema).to have_field(:pet_measurements, 'object')
+
+        pm_schema = schema[:properties][:pet_measurements]
+        expect(pm_schema).to have_field(:weight, 'number', {:description => "Weight in pounds"})
+        expect(pm_schema).to have_field(:height, 'number', {:description => "Height in inches"})
+        expect(pm_schema).to have_field(:num_legs, 'number', {:description => "Number of legs", :required => false})
+      end
+
+      it "should return code 203 with spread out 'pet', encapsulated 'pet_measurements' and encapsulated 'pet_history'" do
+        returns_obj = subject.returns.detect{|e| e.code == 203 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(203)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:pet_name,
+                                                      :animal_type,
+                                                      {:pet_measurements => [:weight, :height,:num_legs]},
+                                                      {:pet_history => [:did_visit_vet, :avg_meals_per_day]},
+                                                      {:additional_histories => [:did_visit_vet, :avg_meals_per_day]}
+                                                     ])
+      end
+      it 'should have the 203 response described in the swagger' do
+        response = swagger_response_for('/pets/{id}/extra_info', 203)
+        expect(response[:description]).to eq('Non-Authoritative Information')
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:required => false})
+        expect(schema).to have_field(:animal_type, 'string')
+        expect(schema).to have_field(:pet_measurements, 'object')
+        expect(schema).to have_field(:pet_history, 'object')
+        expect(schema).to have_field(:additional_histories, 'array')
+
+        pm_schema = schema[:properties][:pet_measurements]
+        expect(pm_schema).to have_field(:weight, 'number', {:description => "Weight in pounds"})
+        expect(pm_schema).to have_field(:height, 'number', {:description => "Height in inches"})
+        expect(pm_schema).to have_field(:num_legs, 'number', {:description => "Number of legs", :required => false})
+
+        ph_schema = schema[:properties][:pet_history]
+        expect(ph_schema).to have_field(:did_visit_vet, 'boolean')
+        expect(ph_schema).to have_field(:avg_meals_per_day, 'number')
+
+        pa_schema = schema[:properties][:additional_histories]
+        expect(pa_schema[:type]).to eq('array')
+        pai_schema = schema[:properties][:additional_histories][:items]
+        expect(pai_schema).to have_field(:did_visit_vet, 'boolean')
+        expect(pai_schema).to have_field(:avg_meals_per_day, 'number')
+      end
+
+      it "should return code matching :unprocessable_entity (422) with spread out 'pet' and 'num_fleas'" do
+        returns_obj = subject.returns.detect{|e| e.code == 422 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(422)
+
+        expect(returns_obj).to match_field_structure([:pet_name,
+                                                      :animal_type,
+                                                      :num_fleas
+                                                     ])
+      end
+      it 'should have the 422 response described in the swagger' do
+        response = swagger_response_for('/pets/{id}/extra_info', 422)
+        expect(response[:description]).to eq('Fleas were discovered on the pet')
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:required => false})
+        expect(schema).to have_field(:animal_type, 'string')
+        expect(schema).to have_field(:num_fleas, 'number')
+      end
+
+    end
+
+  end
+
+  #==============================================================================
+  # PetsUsingSelfDescribingClassesController is a demonstration of how
+  # responses can be described using manual generation of a property description
+  # array
+  #==============================================================================
+
+
+  describe PetsUsingSelfDescribingClassesController do
+
+    describe "PetsController#pets_described_as_class" do
+      subject do
+        desc._methods[:pets_described_as_class]
+      end
+
+      it "should return code 200 with array of entries of the format {'pet_name', 'animal_type'}" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(true)
+
+        expect(returns_obj).to match_field_structure([:pet_name, :animal_type])
+      end
+
+      it 'should have the response described in the swagger' do
+        response = swagger_response_for('/pets_described_as_class')
+        expect(response[:description]).to eq("list of pets")
+
+        schema = response[:schema]
+        expect(schema[:type]).to eq("array")
+
+        a_schema = schema[:items]
+        expect(a_schema).to have_field(:pet_name, 'string', {:description => 'Name of pet', :required => false})
+        expect(a_schema).to have_field(:animal_type, 'string', {:description => 'Type of pet', :enum => ['dog','cat','iguana','kangaroo']})
+      end
+    end
+
+
+    describe "PetsController#pets_with_measurements_described_as_class" do
+      subject do
+        desc._methods[:pets_with_measurements_described_as_class]
+      end
+
+      it "should return code 200 with spread out 'pet' and encapsulated 'pet_measurements'" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:pet_name,
+                                                      :animal_type,
+                                                      {:pet_measurements => [:weight, :height, :num_legs]}
+                                                     ])
+      end
+      it 'should have the 200 response described in the swagger' do
+        response = swagger_response_for('/pets_with_measurements_described_as_class/{id}', 200)
+        expect(response[:description]).to eq('measurements of the pet')
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:required => false})
+        expect(schema).to have_field(:animal_type, 'string')
+        expect(schema).to have_field(:pet_measurements, 'object')
+
+        pm_schema = schema[:properties][:pet_measurements]
+        expect(pm_schema).to have_field(:weight, 'number', {:description => "Weight in pounds"})
+        expect(pm_schema).to have_field(:height, 'number', {:description => "Height in inches"})
+        expect(pm_schema).to have_field(:num_legs, 'number', {:description => "Number of legs", :required => false})
+      end
+    end
+
+    describe "PetsController#pets_with_many_measurements_as_class" do
+      subject do
+        desc._methods[:pets_with_many_measurements_as_class]
+      end
+
+      it "should return code 200 with pet_name (string) and many_pet_measurements (array of objects)" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:pet_name,
+                                                      {:many_pet_measurements => [:weight, :height]}
+                                                     ])
+      end
+
+
+      it 'should have the 200 response described in the swagger' do
+        response = swagger_response_for('/pets_with_many_measurements_as_class/{id}', 200)
+        expect(response[:description]).to eq('measurements of the pet')
+
+        schema = response[:schema]
+        expect(schema).to have_field(:pet_name, 'string', {:required => false})
+        expect(schema).to have_field(:many_pet_measurements, 'array')
+
+        pm_schema = schema[:properties][:many_pet_measurements][:items]
+        expect(pm_schema).to have_field(:weight, 'number', {:description => "Weight in pounds"})
+        expect(pm_schema).to have_field(:height, 'number', {:description => "Height in inches"})
+      end
+    end
+
+  end
+
+
+  #=========================================================
+  # PetsUsingAutoViewsController is a demonstration of how
+  # responses can be described using logic
+  #=========================================================
+
+  describe PetsUsingAutoViewsController do
+
+    describe "PetsController#pet_described_using_automated_view" do
+      subject do
+        desc._methods[:pet_described_using_automated_view]
+      end
+
+      it "should return code 200 with array of entries of the format {'pet_name', 'animal_type'}" do
+        returns_obj = subject.returns.detect{|e| e.code == 200 }
+
+        expect(returns_obj.code).to eq(200)
+        expect(returns_obj.is_array?).to eq(false)
+        expect(returns_obj).to match_field_structure([:pet_name, :animal_type, :age])
+      end
+
+      it 'should have the response described in the swagger' do
+        response = swagger_response_for('/pet_described_using_automated_view/{id}')
+        expect(response[:description]).to eq("like Pet, but different")
+
+        schema = response[:schema]
+        expect(schema[:type]).to eq("object")
+
+        expect(schema).to have_field(:pet_name, 'string', {:required => true})
+        expect(schema).to have_field(:animal_type, 'string', {:required => true})
+        expect(schema).to have_field(:age, 'number', {:required => true})
+      end
+    end
+  end
+
+
+end