apipierails3 0.0.1

data/spec/lib/swagger/rake_swagger_spec.rb

@@ -0,0 +1,139 @@
+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"
+
+  let(:doc_path)  { "user_specified_doc_path" }
+
+  before do
+    Apipie.configuration.doc_path = doc_path
+    Apipie.configuration.swagger_suppress_warnings = true
+    allow(Apipie).to receive(:reload_documentation)
+    subject.invoke(*task_args)
+  end
+
+  describe 'static swagger specification files' do
+
+    after do
+      Dir["#{doc_output}*"].each { |static_file| FileUtils.rm_rf(static_file) }
+    end
+
+    let(:swagger_schema) do
+      File.read(File.join(File.dirname(__FILE__),"openapi_2_0_schema.json"))
+    end
+
+    let(:apidoc_swagger_json) do
+      # note:  the filename ends with '_tmp' because this suffix is passed as a parameter to the rake task
+      File.read("#{doc_output}/schema_swagger_tmp.json")
+    end
+
+    let(:apidoc_swagger) do
+      JSON.parse(apidoc_swagger_json)
+    end
+
+    let(:doc_output) do
+      File.join(::Rails.root, doc_path, 'apidoc')
+    end
+
+    let(:ref_output) do
+      File.join(::Rails.root, doc_path, 'apidoc_ref')
+    end
+
+
+    def expect_param_def(http_method, path, param_name, field, value)
+      params = apidoc_swagger["paths"][path][http_method]["parameters"]
+      param = params.select {|p| p if p["name"]==param_name}[0]
+      expect(param[field]).to eq(value)
+    end
+
+    def expect_tags_def(http_method, path, value)
+      params = apidoc_swagger["paths"][path][http_method]["tags"]
+      expect(params).to eq(value)
+    end
+
+    def body_param_def(http_method, path, param_name)
+      params = apidoc_swagger["paths"][path][http_method]["parameters"]
+      body = params.select {|p| p if p["name"]=="body"}[0]
+      schema_properties = body["schema"]["properties"]
+      # print JSON.pretty_generate(schema_properties)
+      param = (schema_properties.select {|k,v| v if k == param_name })[param_name]
+      # print JSON.pretty_generate(param)
+      param
+    end
+
+    def expect_body_param_def(http_method, path, param_name, field, value)
+      param = body_param_def(http_method, path, param_name)
+      expect(param[field]).to eq(value)
+    end
+
+
+    describe 'apipie:static_swagger_json[development,json,_tmp]' do
+      it "generates static swagger files for the default version of apipie docs" do
+        # print apidoc_swagger_json
+
+        expect(apidoc_swagger["info"]["title"]).to eq("Test app (params in:body)")
+        expect(apidoc_swagger["info"]["version"]).to eq("#{Apipie.configuration.default_version}")
+      end
+
+      it "includes expected values in the generated swagger file" do
+        expect_param_def("get", "/twitter_example/{id}", "screen_name", "in", "query")
+        expect_param_def("put", "/users/{id}", "id", "in", "path")
+        expect_body_param_def("put", "/users/{id}", "oauth", "type", "string")
+        expect_body_param_def("put", "/users/{id}", "user", "type", "object")
+
+        user = body_param_def("put", "/users/{id}", "user")
+        expect(user["properties"]["name"]["type"]).to eq("string")
+
+        expect_param_def("get", "/users/by_department", "department", "in", "query")
+        expect_param_def("get", "/users/by_department", "department", "enum",
+                         ["finance", "operations", "sales", "marketing", "HR"])
+
+        expect_tags_def("get", "/twitter_example/{id}/followers", %w[twitter_example following index search])
+      end
+
+      it "generates a valid swagger file" do
+        # print apidoc_swagger_json
+        expect(JSON::Validator.validate(swagger_schema, apidoc_swagger_json)).to be_truthy
+      end
+    end
+
+    describe 'apipie:static_swagger_json[development,form_data,_tmp]' do
+      it "generates static swagger files for the default version of apipie docs" do
+        # print apidoc_swagger_json
+
+        expect(apidoc_swagger["info"]["title"]).to eq("Test app (params in:formData)")
+        expect(apidoc_swagger["info"]["version"]).to eq("#{Apipie.configuration.default_version}")
+
+      end
+
+      it "includes expected values in the generated swagger file" do
+        expect_param_def("get", "/twitter_example/{id}", "screen_name", "in", "query")
+        expect_param_def("put", "/users/{id}", "id", "in", "path")
+        expect_param_def("put", "/users/{id}", "oauth", "in", "formData")
+        expect_param_def("get", "/users/by_department", "department", "in", "query")
+        expect_param_def("get", "/users/by_department", "department", "enum",
+                         ["finance", "operations", "sales", "marketing", "HR"])
+
+        expect_tags_def("get", "/twitter_example/{id}/followers", %w[twitter_example following index search])
+
+      end
+
+      it "generates a valid swagger file" do
+        # print apidoc_swagger_json
+        expect(JSON::Validator.validate(swagger_schema, apidoc_swagger_json)).to be_truthy
+      end
+    end
+
+    describe 'apipie:did_swagger_change[development,form_data,_tmp]' do
+      it "keeps a reference file" do
+        expect(Pathname(ref_output).children.count).to eq(2)  # one file for each language
+      end
+    end
+  end
+
+end

data/spec/lib/swagger/response_validation_spec.rb

@@ -0,0 +1,104 @@
+require 'spec_helper'
+require 'rack/utils'
+require 'rspec/expectations'
+require 'apipie/rspec/response_validation_helper'
+require "json-schema"
+
+RSpec.describe PetsController, :type => :controller do
+  before :each do
+    Apipie.configuration.swagger_allow_additional_properties_in_response = false
+  end
+
+  it "does not raise error when rendered output matches the described response" do
+    response = get :return_and_validate_expected_response, {format: :json}
+    expect(response).to match_declared_responses
+  end
+
+  it "does not raise error when rendered output (array) matches the described response" do
+    response = get :return_and_validate_expected_array_response, {format: :json}
+    expect(response).to match_declared_responses
+  end
+
+  it "does not raises error when rendered output includes null in the response" do
+    response = get :return_and_validate_expected_response_with_null, {format: :json}
+    expect(response).to match_declared_responses
+  end
+
+  it "does not raise error when rendered output includes null (instead of an object) in the response" do
+    response = get :return_and_validate_expected_response_with_null_object, {format: :json}
+    expect(response).to match_declared_responses
+  end
+
+  it "raises error when a response field has the wrong type" do
+    response = get :return_and_validate_type_mismatch, {format: :json}
+    expect(response).not_to match_declared_responses
+  end
+
+  it "raises error when a response has a missing field" do
+    response = get :return_and_validate_missing_field, {format: :json}
+    expect(response).not_to match_declared_responses
+  end
+
+  it "raises error when a response has an extra property and 'swagger_allow_additional_properties_in_response' is false" do
+    response = get :return_and_validate_extra_property, {format: :json}
+    expect(response).not_to match_declared_responses
+  end
+
+  it "raises error when a response has is array instead of object" do
+    # note: this action returns HTTP 201, not HTTP 200!
+    response = get :return_and_validate_unexpected_array_response, {format: :json}
+    expect(response).not_to match_declared_responses
+  end
+
+  it "does not raise error when a response has an extra property and 'swagger_allow_additional_properties_in_response' is true" do
+    Apipie.configuration.swagger_allow_additional_properties_in_response = true
+    response = get :return_and_validate_extra_property, {format: :json}
+    expect(response).to match_declared_responses
+  end
+
+  it "does not raise error when a response has an extra field and 'additional_properties' is specified in the response" do
+    Apipie.configuration.swagger_allow_additional_properties_in_response = false
+    response = get :return_and_validate_allowed_extra_property, {format: :json}
+    expect(response).to match_declared_responses
+  end
+
+  it "raises error when a response sub-object has an extra field and 'additional_properties' is not specified on it, but specified on the top level of the response" do
+    Apipie.configuration.swagger_allow_additional_properties_in_response = false
+    response = get :sub_object_invalid_extra_property, {format: :json}
+    expect(response).not_to match_declared_responses
+  end
+
+  it "does not rais error when a response sub-object has an extra field and 'additional_properties' is specified on it" do
+    Apipie.configuration.swagger_allow_additional_properties_in_response = false
+    response = get :sub_object_allowed_extra_property, {format: :json}
+    expect(response).to match_declared_responses
+  end
+
+  describe "auto validation" do
+    auto_validate_rendered_views
+    it "raises exception when a response field has the wrong type and auto validation is turned on" do
+      expect { get :return_and_validate_type_mismatch, {format: :json} }.to raise_error(Apipie::ResponseDoesNotMatchSwaggerSchema)
+    end
+
+    it "does not raise an exception when calling an undocumented method" do
+      expect { get :undocumented_method, {format: :json} }.not_to raise_error
+    end
+
+  end
+
+
+  describe "with array field" do
+    it "no error for valid response" do
+      response = get :returns_response_with_valid_array, {format: :json}
+      expect(response).to match_declared_responses
+    end
+
+    it "error if type of element in the array is wrong" do
+      response = get :returns_response_with_invalid_array, {format: :json}
+      expect(response).not_to match_declared_responses
+    end
+  end
+
+
+
+end

data/spec/lib/swagger/swagger_dsl_spec.rb

@@ -0,0 +1,658 @@
+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 get_ref(ref)
+    name = ref.split('#/definitions/')[1].to_sym
+    swagger[:definitions][name]
+  end
+
+  def resolve_refs(schema)
+    if schema['$ref']
+      return get_ref(schema['$ref'])
+    end
+    schema
+  end
+
+  def swagger_response_for(path, code=200, method='get')
+    response = swagger[:paths][path][method][:responses][code]
+    response[:schema] = resolve_refs(response[:schema])
+    response
+  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
+
+
+
+
+  #
+  # Matcher to validate the hierarchy of fields described in an internal 'returns' object (without checking their type)
+  #
+  # For example, code such as:
+  #           returns_obj = Apipie.get_resource_description(...)._methods.returns.detect{|e| e.code=200})
+  #           expect(returns_obj).to match_param_structure([:pet_name, :animal_type, :pet_measurements => [:weight, :height]])
+  #
+  # will verify that the payload structure described for the response of return code 200 is:
+  #           {
+  #             "pet_name": <any>,
+  #             "animal_type": <any>,
+  #             "pet_measurements": {
+  #                 "weight": <any>,
+  #                 "height": <any>
+  #             }
+  #           }
+  #
+  #
+  RSpec::Matchers.define :match_field_structure do |expected|
+    @last_message = nil
+
+    match do |actual|
+      deep_match?(actual, expected)
+    end
+
+    def deep_match?(actual, expected, breadcrumb=[])
+      pending_params = actual.params_ordered.dup
+      expected.each do |expected_param|
+        expected_param_name = expected_param.is_a?(Hash) ? expected_param.keys.first : expected_param
+        actual_param = pending_params.find { |param| param.name.to_s == expected_param_name.to_s }
+        unless actual_param
+          @fail_message = "Couldn't find #{expected_param_name.inspect} among #{pending_params.map(&:name)} in #{breadcrumb.join('.')}"
+          return false
+        else
+          pending_params.delete_if { |p| p.object_id ==  actual_param.object_id }
+        end
+
+        return false unless fields_match?(actual_param, expected_param_name, breadcrumb)
+        if expected_param.is_a? Hash
+          return false unless deep_match?(actual_param.validator, expected_param.values[0], breadcrumb + [expected_param.keys.first])
+        end
+      end
+
+      unless pending_params.empty?
+        @fail_message = "Unexpected properties #{pending_params.map(&:name)} in #{breadcrumb.join('.')}"
+        return false
+      end
+      true
+    end
+
+    def fields_match?(param, expected_name, breadcrumb)
+      return false unless have_field?(param, expected_name, breadcrumb)
+      @fail_message = "expected #{(breadcrumb + [param.name]).join('.')} to eq #{(breadcrumb + [expected_name]).join('.')}"
+      param.name.to_s == expected_name.to_s
+    end
+
+    def have_field?(field, expected_name, breadcrumb)
+      @fail_message = "expected property #{(breadcrumb+[expected_name]).join('.')}"
+      !field.nil?
+    end
+
+    failure_message do |actual|
+      @fail_message
+    end
+  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 = resolve_refs(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_plain_response_with_tags" do
+      subject do
+        desc._methods[:show_plain_response_with_tags]
+      end
+
+      it "should return tags with 'Dogs', 'Cats', and 'LivingBeings'" do
+        returns_obj = subject.tag_list
+        puts returns_obj.inspect
+
+        expect(returns_obj.tags).to eq(%w[Dogs Cats LivingBeings])
+      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 204 with array of integer" do
+        returns_obj = subject.returns.detect{|e| e.code == 204 }
+
+        puts returns_obj.to_json
+        expect(returns_obj.code).to eq(204)
+        expect(returns_obj.is_array?).to eq(false)
+
+        expect(returns_obj).to match_field_structure([:int_array, :enum_array])
+      end
+      it 'should have the 204 response described in the swagger' do
+        response = swagger_response_for('/pets/{id}/extra_info', 204)
+
+        schema = response[:schema]
+        expect(schema).to have_field(:int_array, 'array', {items: {type: 'number'}})
+        expect(schema).to have_field(:enum_array, 'array', {items: {type: 'string', enum: ['v1','v2','v3']}})
+      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
+
+  #==============================================================================
+  # TaggedDogsController is a demonstration of how tags may be defined in a simple
+  # controller class without defining either the controller resource-description
+  # block or the controller's superclass's resource-description block.
+  #==============================================================================
+
+  describe TaggedDogsController do
+    describe "TaggedDogsController#show_as_properties" do
+      subject do
+        desc._methods[:show_as_properties]
+      end
+
+      it "should return tags with 'Dogs', and 'Wolves'" do
+        returns_obj = subject.tag_list
+        puts returns_obj.inspect
+
+        expect(returns_obj.tags).to eq(%w[Dogs Wolves])
+      end
+    end
+  end
+
+  #==============================================================================
+  # TaggedCatsController is a demonstration of how tags may be defined in the
+  # controller's resource description so that they may be automatically prefixed
+  # to a particular operation's tags.
+  #==============================================================================
+
+  describe TaggedCatsController do
+    describe "TaggedCatsController#show_as_properties" do
+      subject do
+        desc._methods[:show_as_properties]
+      end
+
+      it "should return tags with 'Dogs', 'Pets', and 'Animals'" do
+        returns_obj = subject.tag_list
+        puts returns_obj.inspect
+
+        expect(returns_obj.tags).to eq(%w[Dogs Pets Animals])
+      end
+    end
+
+    describe "TaggedCatsController#show_as_same_properties" do
+      subject do
+        desc._methods[:show_as_same_properties]
+      end
+
+      it "should return tags with 'Dogs', 'Pets', 'Puma', and 'Animals'" do
+        returns_obj = subject.tag_list
+        puts returns_obj.inspect
+
+        expect(returns_obj.tags).to eq(%w[Dogs Pets Puma Animals])
+      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