apipie-rails 0.2.2 → 0.2.3

data/.gitignore

@@ -6,6 +6,9 @@ spec/dummy/log/*.log
 spec/dummy/tmp/
 .idea
 Gemfile*.lock
+Gemfile.local
 .rvmrc
+.ruby-version
+.ruby-gemset
 
 .DS_Store

data/CHANGELOG.md

@@ -2,6 +2,17 @@
  Changelog
 ===========
 
+v0.2.3
+------
+
+* add an option to flag an api route as deprecated
+  [#268](https://github.com/Apipie/apipie-rails/pull/268) [@komidore64][]
+* add ability to pass additional options to apipie route
+  [#269](https://github.com/Apipie/apipie-rails/pull/269) [@exAspArk][]
+* enhanced array validator
+  [#259](https://github.com/Apipie/apipie-rails/pull/259) [@mourad-ifeelgoods][]
+
+
 v0.2.2
 ------
 
@@ -11,8 +22,6 @@ v0.2.2
   [#257](https://github.com/Apipie/apipie-rails/pull/257) [@ctria][]
 * reduced rails dependency to development only
   [#266](https://github.com/Apipie/apipie-rails/pull/266) [@klobuczek][]
-* reduced rails dependency to development only
-  [#266](https://github.com/Apipie/apipie-rails/pull/266) [@klobuczek][]
 * add more options to apipie:cache to generate only parts of the
   static pages
   [#262](https://github.com/Apipie/apipie-rails/pull/262) [@mbacovsky][]
@@ -174,3 +183,6 @@ v0.0.15
 [@lsylvester]: https://github.com/lsylverster
 [@ctria]: https://github.com/ctria
 [@klobuczek]: https://github.com/klobuczek
+[@komidore64]: https://github.com/komidore64
+[@exAspArk]: https://github.com/exAspArk
+[@mourad-ifeelgoods]: https://github.com/mourad-ifeelgoods

data/Gemfile

@@ -1,3 +1,7 @@
 source "https://rubygems.org"
 
 gemspec
+
+# load local gemfile
+local_gemfile = File.join(File.dirname(__FILE__), 'Gemfile.local')
+self.instance_eval(Bundler.read_file(local_gemfile)) if File.exist?(local_gemfile)

data/README.rst

@@ -669,14 +669,14 @@ Check parameter value against given regular expression.
    param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
 
 
-ArrayValidator
+EnumValidator
 --------------
 
 Check if parameter value is included given array.
 
 .. code:: ruby
 
-   param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
+   param :enum_param, [100, "one", "two", 1, 2], :desc => "enum validator"
 
 
 ProcValidator
@@ -724,6 +724,49 @@ override parameters described on resource level.
      #...
    end
 
+ArrayValidator
+--------------
+
+Check if the parameter is an array
+
+Additional options
+~~~~~~~~~~~~~~~~~
+
+of
+  Specify the type of items. if not given it accepts an array of any item type
+
+in
+  Specifiy an array of valid items value.
+
+Examples
+~~~~~~~~
+
+Assert `things` is an array of any items
+
+.. code:: ruby
+
+  param :things, Array
+
+Assert `hits` must be an array of integer values
+
+.. code:: ruby
+
+  param :hits, Array, of: Integer
+
+Assert `colors` must be an array of valid string values
+
+.. code:: ruby
+
+  param :colors, Array, in: ["red", "green", "blue"]
+
+
+The retrieving of valid items can be deferred until needed using a lambda. It is evaluated only once
+
+.. code:: ruby
+
+  param :colors, Array, in: ->  { Color.all.pluck(:name) }
+
+
 NestedValidator
 -------------
 
@@ -817,17 +860,21 @@ the resource belong to `config.default_version` ("1.0" by default)
      api_versions "1", "2"
    end
 
-   api :GET, "/api/users/"
+   api :GET, "/api/users/", "List: users"
    api_version "1"
    def index
      # ...
    end
 
+   api :GET, "/api/users/", "List: users", :deprecated => true
+
 In the example above we say the whole controller/resource is defined
 for versions "1" and "2", but we override this with explicitly saying
 `index` belongs only to version "1". Also inheritance works (therefore
 we can specify the api_version for the parent controller and all
-children will know about that).
+children will know about that). Routes can be flagged as deprecated
+and an annotation will be added to them when viewing in the API
+documentation.
 
 From the Apipie API perspective, the resources belong to version.
 With versioning, there are paths like this provided by apipie:

data/app/views/apipie/apipies/index.html.erb

@@ -30,7 +30,12 @@
       <% api[:methods].each do |m| %>
         <% m[:apis].each do |a| %>
           <tr>
-            <td><a href='<%= m[:doc_url] %><%= @doc[:link_extension] %>'><%= a[:http_method] %> <%= a[:api_url] %></a></td>
+            <td>
+              <a href='<%= m[:doc_url] %><%= @doc[:link_extension] %>'><%= a[:http_method] %> <%= a[:api_url] %></a>
+              <% if a[:deprecated] %>
+                <code>DEPRECATED</code>
+              <% end %>
+            </td>
             <td width='60%'><%= a[:short_description] %></td>
           </tr>
         <% end %>

data/app/views/apipie/apipies/method.html.erb

@@ -18,7 +18,11 @@
 <% @method[:apis].each do |api| %>
   <div class='page-header'>
     <h1>
-      <%= api[:http_method] %> <%= api[:api_url] %><br>
+      <%= api[:http_method] %> <%= api[:api_url] %>
+      <% if api[:deprecated] %>
+        <code>DEPRECATED</code>
+      <% end %>
+      <br>
       <small><%= raw api[:short_description] %></small>
     </h1>
   </div>

data/app/views/apipie/apipies/resource.html.erb

@@ -47,7 +47,11 @@
            data-toggle='collapse'
            data-parent='#accordion'>
             <%= api[:http_method] %> <%= api[:api_url] %>
-          </a><br>
+          </a>
+          <% if api[:deprecated] %>
+            <code>DEPRECATED</code>
+          <% end %>
+          <br>
           <small><%= raw api[:short_description] %></small>
         </h2>
       <% end %>

data/lib/apipie/dsl_definition.rb

@@ -79,7 +79,7 @@ module Apipie
       #
       def api(method, path, desc = nil, options={}) #:doc:
         return unless Apipie.active_dsl?
-        _apipie_dsl_data[:api_args] << [method, path, desc]
+        _apipie_dsl_data[:api_args] << [method, path, desc, options]
       end
 
       # Reference other similar method

data/lib/apipie/method_description.rb

@@ -5,12 +5,13 @@ module Apipie
 
     class Api
 
-      attr_accessor :short_description, :path, :http_method
+      attr_accessor :short_description, :path, :http_method, :options
 
-      def initialize(method, path, desc)
+      def initialize(method, path, desc, options)
         @http_method = method.to_s
         @path = path
         @short_description = desc
+        @options = options
       end
 
     end
@@ -22,8 +23,8 @@ module Apipie
       @resource = resource
       @from_concern = dsl_data[:from_concern]
 
-      @apis = dsl_data[:api_args].map do |method, path, desc|
-        MethodDescription::Api.new(method, concern_subst(path), concern_subst(desc))
+      @apis = dsl_data[:api_args].map do |mthd, path, desc, opts|
+        MethodDescription::Api.new(mthd, concern_subst(path), concern_subst(desc), opts)
       end
 
       desc = dsl_data[:description] || ''
@@ -113,7 +114,8 @@ module Apipie
         {
           :api_url => create_api_url(api),
           :http_method => api.http_method.to_s,
-          :short_description => Apipie.app.translate(api.short_description, lang)
+          :short_description => Apipie.app.translate(api.short_description, lang),
+          :deprecated => api.options[:deprecated]
         }
       end
     end

data/lib/apipie/routing.rb

@@ -1,11 +1,11 @@
 module Apipie
   module Routing
     module MapperExtensions
-      def apipie
+      def apipie(options = {})
         namespace "apipie", :path => Apipie.configuration.doc_base_url do
           get 'apipie_checksum', :to => "apipies#apipie_checksum", :format => "json"
           constraints(:version => /[^\/]+/, :resource => /[^\/]+/, :method => /[^\/]+/) do
-            get("(:version)/(:resource)/(:method)" => "apipies#index", :as => :apipie)
+            get(options.reverse_merge("(:version)/(:resource)/(:method)" => "apipies#index", :as => :apipie))
           end
         end
       end

data/lib/apipie/validator.rb

@@ -134,8 +134,7 @@ module Apipie
     end
 
     # arguments value must be one of given in array
-    class ArrayValidator < BaseValidator
-
+    class EnumValidator < BaseValidator
       def initialize(param_description, argument)
         super(param_description)
         @array = argument
@@ -154,6 +153,73 @@ module Apipie
       end
     end
 
+    # arguments value must be an array
+    class ArrayValidator < Apipie::Validator::BaseValidator
+      def initialize(param_description, argument, options={})
+        super(param_description)
+        @type = argument
+        @items_type = options[:of]
+        @items_enum = options[:in]
+      end
+
+      def validate(values)
+        return false unless process_value(values).respond_to?(:each)
+        process_value(values).all? { |v| validate_item(v)}
+      end
+
+      def process_value(values)
+        values || []
+      end
+
+      def description
+        "Must be an array of #{items}"
+      end
+
+      def self.build(param_description, argument, options={}, block)
+        if argument == Array && !block.is_a?(Proc)
+          self.new(param_description, argument, options)
+        end
+      end
+
+      private
+
+      def enum
+        if @items_enum.kind_of?(Proc)
+          @items_enum = Array(@items_enum.call)
+        end
+        @items_enum
+      end
+
+      def validate_item(value)
+        has_valid_type?(value) &&
+          is_valid_value?(value)
+      end
+
+      def has_valid_type?(value)
+        if @items_type
+          value.kind_of?(@items_type)
+        else
+          true
+        end
+      end
+
+      def is_valid_value?(value)
+        if enum
+          enum.include?(value)
+        else
+          true
+        end
+      end
+
+      def items
+        unless enum
+          @items_type || "any type"
+        else
+          enum.inspect
+        end
+      end
+    end
+
     class ArrayClassValidator < BaseValidator
 
       def initialize(param_description, argument)

data/lib/apipie/version.rb

@@ -1,3 +1,3 @@
 module Apipie
-  VERSION = '0.2.2'
+  VERSION = '0.2.3'
 end

data/spec/controllers/users_controller_spec.rb

@@ -517,7 +517,7 @@ EOS2
 
       param = a.params[:array_param]
       param.desc.should eq("\n<p>array validator</p>\n")
-      param.validator.class.should be(Apipie::Validator::ArrayValidator)
+      param.validator.class.should be(Apipie::Validator::EnumValidator)
       param.validator.instance_variable_get("@array").should
         eq([100, "one", "two", 1, 2])
 

data/spec/lib/method_description_spec.rb

@@ -26,6 +26,18 @@ describe Apipie::MethodDescription do
 
   end
 
+  describe "deprecated flag" do
+    before(:each) do
+      @resource = Apipie::ResourceDescription.new(ApplicationController, "dummy")
+    end
+
+    it "should return the deprecated flag when provided" do
+      dsl_data[:api_args] = [[:GET, "/foo/bar", "description", :deprecated => true]]
+      method = Apipie::MethodDescription.new(:a, @resource, dsl_data)
+      method.method_apis_to_json.first[:deprecated].should == true
+    end
+  end
+
   describe "params descriptions" do
 
     before(:each) do

data/spec/lib/validators/array_validator_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+module Apipie::Validator
+  describe ArrayValidator do
+
+    let(:param_desc) { double(:param_desc) }
+
+    context "with no constraint" do
+      let(:validator) { ArrayValidator.new(param_desc, Array) }
+      it "accepts any array" do
+        expect(validator.validate([42, 'string', true])).to eq(true)
+      end
+
+      it "accepts empty array" do
+        expect(validator.validate([])).to eq(true)
+        expect(validator.validate(nil)).to eq(true)
+      end
+
+      it "does not accepts non array" do
+        expect(validator.validate(42)).to eq(false)
+        expect(validator.validate(true)).to eq(false)
+        expect(validator.validate('string')).to eq(false)
+      end
+    end
+
+    context "with a constraint on items type" do
+      let(:validator) { ArrayValidator.new(param_desc, Array, of: String) }
+
+      it "accepts array of specified type" do
+        expect(validator.validate(['string1', 'string2'])).to eq(true)
+      end
+
+      it "accepts empty array" do
+        expect(validator.validate([])).to eq(true)
+      end
+
+      it "does not accepts array with other types" do
+        expect(validator.validate(['string1', true])).to eq(false)
+      end
+    end
+
+    context "with a constraint on items value" do
+      let(:validator) { ArrayValidator.new(param_desc, Array, in: [42, 'string', true]) }
+
+      it "accepts array of valid values" do
+        expect(validator.validate([42, 'string'])).to eq(true)
+      end
+
+      it "accepts empty array" do
+        expect(validator.validate([])).to eq(true)
+      end
+
+      it "does not accepts array with invalid values" do
+        expect(validator.validate([42, 'string', 'foo'])).to eq(false)
+      end
+
+      it "accepts a proc as list of valid values" do
+        validator = ArrayValidator.new(param_desc, Array, in: -> { [42, 'string', true] })
+        expect(validator.validate([42, 'string'])).to eq(true)
+        expect(validator.validate([42, 'string', 'foo'])).to eq(false)
+      end
+    end
+
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: apipie-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-24 00:00:00.000000000 Z
+date: 2014-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -297,6 +297,7 @@ files:
 - spec/lib/rake_spec.rb
 - spec/lib/resource_description_spec.rb
 - spec/lib/validator_spec.rb
+- spec/lib/validators/array_validator_spec.rb
 - spec/spec_helper.rb
 - spec/support/rake.rb
 homepage: http://github.com/Pajk/apipie-rails
@@ -384,6 +385,7 @@ test_files:
 - spec/lib/rake_spec.rb
 - spec/lib/resource_description_spec.rb
 - spec/lib/validator_spec.rb
+- spec/lib/validators/array_validator_spec.rb
 - spec/spec_helper.rb
 - spec/support/rake.rb
 has_rdoc: