apipierails3 0.0.1

data/spec/dummy/Rakefile

@@ -0,0 +1,7 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+require 'rake'
+
+Dummy::Application.load_tasks

data/spec/dummy/app/controllers/api/base_controller.rb

@@ -0,0 +1,4 @@
+module Api
+  class BaseController < ActionController::Base
+  end
+end

data/spec/dummy/app/controllers/api/v1/architectures_controller.rb

@@ -0,0 +1,43 @@
+module Api
+  module V1
+    class ArchitecturesController < V1::BaseController
+      resource_description { name 'Architectures' }
+      api :GET, "/architectures/", "List all architectures."
+      def index
+      end
+
+      api :GET, "/architectures/:id/", "Show an architecture."
+      def show
+      end
+
+      def_param_group :timestamps do
+        param :created_at, String
+        param :updated_at, String
+      end
+
+      def_param_group :arch do
+        param :architecture, Hash, :required => true do
+          param :name, String, :required => true
+          param :description, String, :required => true
+          param_group :timestamps
+        end
+      end
+
+      api :POST, "/architectures/", "Create an architecture."
+      param_group :arch
+      def create
+      end
+
+      api :PUT, "/architectures/:id/", "Update an architecture."
+      param :architecture, Hash, :required => true do
+        param :name, String
+      end
+      def update
+      end
+
+      api :DELETE, "/architecturess/:id/", "Delete an architecture."
+      def destroy
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v1/base_controller.rb

@@ -0,0 +1,11 @@
+module Api
+  module V1
+    class BaseController < Api::BaseController
+      resource_description do
+        api_version '1.0'
+        app_info 'Version 1.0 description'
+        api_base_url '/api/v1'
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v2/architectures_controller.rb

@@ -0,0 +1,30 @@
+module Api
+  module V2
+    class ArchitecturesController < V2::BaseController
+      resource_description { name 'Architectures' }
+      api :GET, "/architectures/", "List all architectures."
+      def index
+      end
+
+      api :GET, "/architectures/:id/", "Show an architecture."
+      def show
+      end
+
+      api :POST, "/architectures/", "Create an architecture."
+      param_group :arch, Api::V1::ArchitecturesController
+      def create
+      end
+
+      api :PUT, "/architectures/:id/", "Update an architecture."
+      param :architecture, Hash, :required => true do
+        param :name, String
+      end
+      def update
+      end
+
+      api :DELETE, "/architecturess/:id/", "Delete an architecture."
+      def destroy
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v2/base_controller.rb

@@ -0,0 +1,11 @@
+module Api
+  module V2
+    class BaseController < Api::BaseController
+      resource_description do
+        api_version '2.0'
+        app_info 'Version 2.0 description'
+        api_base_url '/api/v2'
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v2/nested/architectures_controller.rb

@@ -0,0 +1,32 @@
+module Api
+  module V2
+    module Nested
+      class ArchitecturesController < V2::BaseController
+        resource_description { name 'Architectures' }
+        api :GET, "/nested/architectures/", "List all nested architectures."
+        def index
+        end
+
+        api :GET, "/nested/architectures/:id/", "Show a nested architecture."
+        def show
+        end
+
+        api :POST, "/nested/architectures/", "Create a nested architecture."
+        param_group :arch, Api::V1::ArchitecturesController
+        def create
+        end
+
+        api :PUT, "/nested/architectures/:id/", "Update a nested architecture."
+        param :architecture, Hash, :required => true do
+          param :name, String
+        end
+        def update
+        end
+
+        api :DELETE, "/architecturess/:id/", "Delete a nested architecture."
+        def destroy
+        end
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/api/v2/nested/resources_controller.rb

@@ -0,0 +1,33 @@
+module Api
+  module V2
+    class Nested::ResourcesController < V2::BaseController
+      resource_description do 
+        name 'Resources'
+        resource_id "resource"
+      end
+      api :GET, "/nested/resources/", "List all nested resources."
+      def index
+      end
+
+      api :GET, "/nested/resources/:id/", "Show a nested resource."
+      def show
+      end
+
+      api :POST, "/nested/resources/", "Create a nested resource."
+      param_group :arch, Api::V1::ArchitecturesController
+      def create
+      end
+
+      api :PUT, "/nested/resources/:id/", "Update a nested resource."
+      param :architecture, Hash, :required => true do
+        param :name, String
+      end
+      def update
+      end
+
+      api :DELETE, "/resources/:id/", "Delete a nested resource."
+      def destroy
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+class ApplicationController < ActionController::Base
+  before_filter :run_validations
+  
+  resource_description do
+    param :oauth, String, :desc => "Authorization", :required => false
+
+    returns :code => 401 do
+      property :reason, String, "Why authorization was denied"
+    end
+  end
+
+  def run_validations
+    if Apipie.configuration.validate == :explicitly
+      apipie_validations
+    end
+  end
+
+end

data/spec/dummy/app/controllers/concerns/extending_concern.rb

@@ -0,0 +1,11 @@
+module Concerns
+  module ExtendingConcern
+    extend Apipie::DSL::Concern
+
+    update_api(:create) do
+      param :user, Hash do
+        param :from_concern, String, :desc => 'param from concern', :allow_nil => false
+      end
+    end
+  end
+end

data/spec/dummy/app/controllers/concerns/sample_controller.rb

@@ -0,0 +1,41 @@
+module Concerns
+  module SampleController
+    extend Apipie::DSL::Concern
+
+    api!
+    def index
+      render :plain => "OK #{params.inspect}"
+    end
+
+    api :GET, '/:resource_id/:id'
+    param :id, String
+    def show
+      render :plain => "OK #{params.inspect}"
+    end
+
+    def_param_group :concern do
+      param :concern, Hash, :required => true, :action_aware => true do
+        param :name, String, "Name of a :concern"
+        param :concern_type, String
+      end
+    end
+
+    api :POST, '/:resource_id', "Create a :concern"
+    param_group :concern
+    def create
+      render :plain => "OK #{params.inspect}"
+    end
+
+    api :PUT, '/:resource_id/:id'
+    param :id, String
+    param_group :concern
+    def update
+      render :plain => "OK #{params.inspect}"
+    end
+
+    api :GET, '/:resource_id/:custom_subst'
+    def custom
+      render :plain => "OK #{params.inspect}"
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+class ConcernsController < ApplicationController
+
+  resource_description { resource_id 'concern_resources' }
+
+  apipie_concern_subst(:concern => 'user', :custom_subst => 'custom', 'string_subst' => 'string')
+  include ::Concerns::SampleController
+
+end

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

@@ -0,0 +1,14 @@
+class ExtendedController < ApplicationController
+
+  api :POST, '/extended'
+  param :user, Hash do
+    param :name, String
+    param :password, String
+  end
+  def create
+  end
+
+  apipie_update_params([:create]) do
+    param :admin, :boolean
+  end
+end

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

@@ -0,0 +1,5 @@
+class FilesController < ApplicationController
+  def download
+    render :text => "dummy file body for #{params[:file_path]}"
+  end
+end

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

@@ -0,0 +1,31 @@
+class OverriddenConcernsController < ApplicationController
+
+  resource_description { resource_id 'overridden_concern_resources' }
+
+  apipie_concern_subst(:concern => 'user')
+  include ::Concerns::SampleController
+
+  def_param_group :concern do
+    param :concern, String
+  end
+
+  api :PUT, '/:resource_id/:id'
+  param :custom_parameter, String, "New parameter added by the overriding method"
+  param_group :concern, ::Concerns::SampleController
+  def update
+    super
+  end
+
+  api :POST, '/:resource_id', "Create a :concern"
+  param_group :concern
+  def create
+    super
+  end
+
+  api :GET, '/:resource_id/custom'
+  param :concern, String
+  def custom
+    render :text => "OK #{params.inspect}"
+  end
+
+end

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
+