apipie-rails 0.3.6 → 0.5.17

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

@@ -0,0 +1,408 @@
+#
+# The PetsController defined here provides examples for different ways
+# in which the 'returns' DSL directive can be used with the existing
+# Apipie DSL elements 'param' and 'param_group'
+#
+
+class PetsController < ApplicationController
+  resource_description do
+    description 'A controller to test "returns"'
+    short 'Pets'
+    path '/pets'
+
+    param :common_param, Integer, :desc => "A param that can optionally be passed to all Pet methods", :required => false
+
+    returns :code => 404 do
+      property :error_message, String, "description of the error"
+    end
+
+  end
+
+  #-----------------------------------------------------------
+  # simple 'returns' example: a method that returns a pet record
+  #-----------------------------------------------------------
+  api :GET, "/pets/:id/as_properties", "Get a pet record"
+  returns :code => 200 do
+    property :pet_name, String, :desc => "Name of pet", :required => false
+    property :animal_type, ['dog','cat','iguana','kangaroo'], :desc => "Type of pet"   # required by default, because this is a 'property'
+  end
+  returns :code => 404 do
+    property :another_error_message, String, :desc => "Overriding the response description from the Pets resource"
+  end
+  def show_as_properties
+    render :plain => "showing pet properties"
+  end
+
+
+  #-----------------------------------------------------------
+  # same example as above, but this time the properties are defined
+  # in a param group
+  #-----------------------------------------------------------
+  def_param_group :pet do
+    property :pet_name, String, :desc => "Name of pet", :required => false
+    property :animal_type, ['dog','cat','iguana','kangaroo'], :desc => "Type of pet"   # required by default, because this is a 'property'
+  end
+
+  api :GET, "/pets/:id/as_param_group_of_properties", "Get a pet record"
+  returns :pet, :code => 200, :desc => "The pet"
+  def show_as_param_group_of_properties
+    render :plain => "showing pet properties defined as param groups"
+  end
+
+  #-----------------------------------------------------------
+  #  Method returning an array of the :pet param_group
+  #-----------------------------------------------------------
+  api :GET, "/pets", "Get all pets"
+  returns :array_of => :pet, :desc => "list of pets"
+  def index
+    render :plain => "all pets"
+  end
+
+
+  #-----------------------------------------------------------
+  # mixing request/response and response-only parameters
+  #
+  # the param_group :pet_with_id has several parameters which are
+  # not expectd in the request, but would show up in the response
+  # and vice versa
+  #-----------------------------------------------------------
+  def_param_group :pet_with_id do
+    param :pet_id, Integer, :desc => "id of pet", :required => true
+    param :pet_name, String, :desc => "Name of pet", :required => false, :only_in => :response
+    param :partial_match_allowed, [true, false], :desc => "Partial match allowed?", :required => false, :only_in => :request
+    property :animal_type, ['dog','cat','iguana','kangaroo'], :desc => "Type of pet"   # this is implicitly :only_in => :response
+  end
+
+  api :GET, "/pets/pet_by_id", "Get a pet record with the pet id in the body of the request"
+  param_group :pet_with_id # only the pet_id is expected to be in here
+  returns :param_group => :pet_with_id, :code => 200
+  def show_pet_by_id
+    render :plain => "returning a record with 3 fields"
+  end
+
+
+
+  #-----------------------------------------------------------
+  # example with multiple param groups
+  #-----------------------------------------------------------
+  def_param_group :owner do   # a param group that can be used to describe inputs as well as outputs
+    param :owner_name, String
+  end
+  def_param_group :user_response do # a param group that can be used to describe outputs only
+    property :vote, [true,false]
+  end
+
+  api :GET, "/pets/by_owner_name/did_vote", "did any of the pets owned by the given user vote?"
+  param_group :owner, :desc => "look up the user by name"
+  returns :code => 200 do
+    param_group :owner
+    param_group :user_response
+  end
+  returns :code => 404  # no body
+  def get_vote_by_owner_name
+    render :plain => "no pets have voted"
+  end
+
+
+  #-----------------------------------------------------------
+  # a method returning multiple codes,
+  # some of which have a complex data structure
+  #-----------------------------------------------------------
+  def_param_group :pet_measurements do
+    property :pet_measurements, Hash do
+      property :weight, Integer, :desc => "Weight in pounds"
+      property :height, Integer, :desc => "Height in inches"
+      property :num_legs, Integer, :desc => "Number of legs", :required => false
+    end
+  end
+
+  def_param_group :pet_history do
+    property :did_visit_vet, [true,false], :desc => "Did the pet visit the veterinarian"
+    property :avg_meals_per_day, Float, :desc => "Average number of meals per day"
+  end
+
+  api :GET, "/pets/:id/extra_info", "Get extra information about a pet"
+  returns :code => 201, :desc => "Found a pet" do
+    param_group :pet
+  end
+  returns :code => 202 do
+    param_group :pet
+    param_group :pet_measurements
+  end
+  returns :code => 203 do
+    param_group :pet
+    param_group :pet_measurements
+    property 'pet_history', Hash do  # the pet_history param_group does not contain a wrapping object,
+                                     # so create one manually
+      param_group :pet_history
+    end
+    property 'additional_histories', :array_of => Hash do
+      param_group :pet_history
+    end
+  end
+  returns :code => 204 do
+    property :int_array, :array_of => Integer
+    property :enum_array, :array_of => ['v1','v2','v3']
+  end
+  returns :code => :unprocessable_entity, :desc => "Fleas were discovered on the pet" do
+    param_group :pet
+    property :num_fleas, Integer, :desc => "Number of fleas on this pet"
+  end
+  def show_extra_info
+    render :plain => "please disinfect your pet"
+  end
+
+
+  #=======================================================================
+  # Methods for testing response validation
+  #=======================================================================
+
+
+  #-----------------------------------------------------------
+  # A method which returns the response as described
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :a_number, Integer
+    property :an_optional_number, Integer, :required=>false
+  end
+  def return_and_validate_expected_response
+    result =  {
+        a_number: 3
+    }
+    render :json => result
+  end
+
+  #-----------------------------------------------------------
+  # A method which returns a null value in the response
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :a_number, Integer
+    property :an_optional_number, Integer, :required=>false
+  end
+  def return_and_validate_expected_response_with_null
+    result =  {
+        a_number: nil
+    }
+    render :json => result
+  end
+
+  #-----------------------------------------------------------
+  # A method which returns a null value in the response instead of an object
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :an_object, Hash do
+      property :an_optional_number, Integer, :required=>false
+    end
+  end
+  def return_and_validate_expected_response_with_null_object
+    result =  {
+        an_object: nil
+    }
+    render :json => result
+  end
+
+  #-----------------------------------------------------------
+  # A method which returns an array response as described
+  #-----------------------------------------------------------
+  def_param_group :two_numbers do
+    property :a_number, Integer
+    property :an_optional_number, Integer, :required=>false
+  end
+
+  api!
+  returns :code => 200, :array_of => :two_numbers
+  def return_and_validate_expected_array_response
+    result =  [{
+                   a_number: 3
+               }]
+    render :json => result
+  end
+
+  #-----------------------------------------------------------
+  # A method which returns an array response when it is expected to return an object
+  # (note that response code is set here to 201)
+  #-----------------------------------------------------------
+  api!
+  returns :two_numbers, :code => 201
+  def return_and_validate_unexpected_array_response
+    result =  [{
+                   a_number: 3
+               }]
+    render :status => 201, :json => result
+  end
+
+  #-----------------------------------------------------------
+  # A method which has a response that does not match the output type
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :a_number, String
+  end
+  def return_and_validate_type_mismatch
+    result =  {
+        a_number: 3
+    }
+    render :json => result
+  end
+
+  #-----------------------------------------------------------
+  # A method with no documentation
+  #-----------------------------------------------------------
+  def undocumented_method
+    render :json => {:result => "ok"}
+  end
+
+  #-----------------------------------------------------------
+  # A method which has a response with a missing field
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :a_number, Integer
+    property :another_number, Integer
+  end
+  def return_and_validate_missing_field
+    result =  {
+        a_number: 3
+    }
+    render :json => result
+  end
+
+
+  #-----------------------------------------------------------
+  # A method which has a response with an extra property
+  # (should raise a validation error by default)
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :a_number, Integer
+  end
+  def return_and_validate_extra_property
+    result =  {
+        a_number: 3,
+        another_number: 4
+    }
+    render :json => result
+  end
+
+
+  #-----------------------------------------------------------
+  # A method which has a response with an extra property, but 'additional_properties' is specified
+  # (should not raise a validation error by default)
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200, :additional_properties => true do
+    property :a_number, Integer
+  end
+  def return_and_validate_allowed_extra_property
+    result =  {
+        a_number: 3,
+        another_number: 4
+    }
+    render :json => result
+  end
+
+  #-----------------------------------------------------------
+  # Sub-object in response has an extra property. 'additional_properties' is specified on the response, but not on the object
+  # (should raise a validation error by default)
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200, :additional_properties => true do
+    property :an_object, Hash do
+      property :a_number, Integer
+    end
+  end
+  def sub_object_invalid_extra_property
+    result =  {
+        an_object: {
+            a_number: 2,
+            an_extra_number: 3
+        }
+    }
+    render :json => result
+  end
+
+
+  #-----------------------------------------------------------
+  # Sub-object in response has an extra property. 'additional_properties' is specified on the object, but not on the response
+  # (should not raise a validation error by default)
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200, :additional_properties => false do
+    property :an_object, Hash, :additional_properties => true do
+      property :a_number, Integer
+    end
+  end
+  def sub_object_allowed_extra_property
+    result =  {
+        an_object: {
+            a_number: 2,
+            an_extra_number: 3
+        }
+    }
+    render :json => result
+  end
+
+  #=======================================================================
+  # Methods for testing array field responses
+  #=======================================================================
+
+  #-----------------------------------------------------------
+  # A method which returns the response as described (one field is an array of objects)
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :a_number, Integer
+    property :array_of_objects, :array_of => Hash do
+      property :number1, Integer, :required=>true
+      property :number2, Integer, :required=>true
+    end
+  end
+  def returns_response_with_valid_array
+    result =  {
+        a_number: 3,
+        array_of_objects: [
+            {number1: 1, number2: 2},
+            {number1: 10, number2: 20}
+        ]
+    }
+    render :json => result
+  end
+
+
+  #-----------------------------------------------------------
+  # A method which returns an incorrect response (wrong field type inside array)
+  #-----------------------------------------------------------
+  api!
+  returns :code => 200 do
+    property :a_number, Integer
+    property :array_of_objects, :array_of => Hash do
+      property :number1, Integer, :required=>true
+      property :number2, Integer, :required=>true
+    end
+  end
+  def returns_response_with_invalid_array
+    result =  {
+        a_number: 3,
+        array_of_objects: [
+            {number1: 1, number2: 2},
+            {number1: 10, number2: "this should have been a number"}
+        ]
+    }
+    render :json => result
+  end
+
+
+  #-----------------------------------------------------------
+  # A method with simple tags.
+  #-----------------------------------------------------------
+  api!
+  tags(%w[Dogs Cats LivingBeings])
+  def show_plain_response_with_tags
+    render :plain => "showing pet properties"
+  end
+
+end
+

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/dummy/app/controllers/tagged_cats_controller.rb

@@ -0,0 +1,32 @@
+#
+# The TagsController defined here provides an example of a resource_description
+# defining a set of tags for the contained methods to include.
+#
+
+class TaggedCatsController < ActionController::Base
+  resource_description do
+    description 'A controller to test "returns"'
+    short 'Pets'
+    path '/pets'
+
+    tags(%w[Dogs Pets])
+  end
+
+  #-----------------------------------------------------------
+  # simple 'returns' example: a method that returns a cat record
+  #-----------------------------------------------------------
+  api :GET, "/pets/:id/as_properties", "Get a cat record"
+  tags(%w[Animals])
+  def show_as_properties
+    render :plain => "showing pet properties"
+  end
+
+  #-----------------------------------------------------------
+  # simple 'returns' example: a method that returns another cat record
+  #-----------------------------------------------------------
+  api :GET, "/pets/:id/as_same_properties", "Get a cat record"
+  tags("Puma", "Animals")
+  def show_as_same_properties
+    render :plain => "showing pet properties"
+  end
+end

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

@@ -0,0 +1,15 @@
+#
+# The TagsController defined here provides an example of a
+# tags call without a resource description.
+#
+
+class TaggedDogsController < ActionController::Base
+  #-----------------------------------------------------------
+  # simple 'returns' example: a method that returns a cat record
+  #-----------------------------------------------------------
+  api :GET, "/pets/:id/as_properties", "Get a dog record"
+  tags(%w[Dogs Wolves])
+  def show_as_properties
+    render :plain => "showing pet properties"
+  end
+end

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

@@ -299,4 +299,9 @@ class TwitterExampleController < ApplicationController
     render :text => 'twitter example'
   end
   
+  api :GET, '/twitter_example/{id}/followers', 'Find the followers for the given screen name'
+  tags %w[following index search]
+  def followers
+    render :text => 'followers'
+  end
 end