restapi 0.0.1

data/lib/restapi/railtie.rb

@@ -0,0 +1,9 @@
+module Restapi
+  class Railtie < Rails::Railtie
+    initializer 'restapi.controller_additions' do
+      ActiveSupport.on_load :action_controller do
+        extend Restapi::DSL
+      end
+    end
+  end
+end

data/lib/restapi/resource_description.rb

@@ -0,0 +1,75 @@
+module Restapi
+  
+  # Resource description
+  # 
+  # version - api version (1)
+  # description
+  # path - relative path (/api/articles)
+  # methods - array of keys to Restapi.method_descriptions (array of Restapi::MethodDescription)
+  # name - human readable alias of resource (Articles)
+  # id - resouce name
+  class ResourceDescription
+    
+    attr_reader :_short_description, :_full_description, :_methods, :_id, :_path, :_version, :_name, :_params
+    
+    def initialize(resource_name, &block)
+      @_methods = []
+      @_params = Hash.new
+
+      @_id = resource_name
+      @_version = "1"
+      @_name = @_id.humanize
+      @_full_description = ""
+      @_short_description = ""
+      @_path = ""
+      
+      block.arity < 1 ? instance_eval(&block) : block.call(self) if block_given?
+    end
+    
+    def param(param_name, *args, &block)
+      @_params[param_name] = Restapi::ParamDescription.new(param_name, *args, &block)
+    end
+    
+    def path(path); @_path = path; end
+    def version(version); @_version = version; end
+    def name(name); @_name = name; end
+    def short(short); @_short_description = short; end
+    alias :short_description :short
+    def desc(description)
+      description ||= ''
+      @_full_description = Restapi.rdoc.convert(description.strip_heredoc)
+    end
+    alias :description :desc
+    alias :full_description :desc
+    
+    # add description of resource method
+    def add_method(mapi_key)
+      @_methods << mapi_key
+      @_methods.uniq!
+    end
+    
+    def doc_url; "#{Restapi.configuration.doc_base_url}/#{@_id}"; end
+    def api_url; "#{Restapi.configuration.api_base_url}#{@_path}"; end
+    
+    def to_json(method_name = nil)
+
+      _methods = if method_name.blank?
+        @_methods.collect { |key| Restapi.method_descriptions[key].to_json }
+      else
+        [Restapi.method_descriptions[[@_id, method_name].join('#')].to_json]
+      end
+
+      {
+        :doc_url => doc_url,
+        :api_url => api_url,
+        :name => @_name,
+        :short_description => @_short_description,
+        :full_description => @_full_description,
+        :version => @_version,
+        :methods => _methods
+      }
+    end
+
+  end
+  
+end

data/lib/restapi/restapi_module.rb

@@ -0,0 +1,54 @@
+require "restapi/application"
+require "ostruct"
+require "erb"
+
+module Restapi
+
+  def self.rdoc
+    @rdoc ||= RDoc::Markup::ToHtml.new
+  end
+  
+  def self.convert_markup(text)
+    Restapi.rdoc.convert(text.strip_heredoc)
+  end
+
+  def self.app
+    @application ||= Restapi::Application.new
+  end
+  
+  def self.to_json(resource_name = nil, method_name = nil)
+    app.to_json(resource_name, method_name)
+  end
+
+  # all calls delegated to Restapi::Application instance
+  def self.method_missing(method, *args, &block)
+    app.respond_to?(method) ? app.send(method, *args, &block) : super
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  class Configuration
+    attr_accessor :app_name, :app_info, :copyright, :markup_language, :validate, :api_base_url, :doc_base_url
+
+    def app_info=(text)
+      @app_info = Restapi.convert_markup(text)
+    end
+    
+    def initialize
+      @markup_language = :rdoc
+      @app_name = "Another API"
+      @app_info = "Another API description"
+      @copyright = nil
+      @validate = true
+      @api_base_url = ""
+      @doc_base_url = "/apidoc"
+    end
+  end
+
+end

data/lib/restapi/routing.rb

@@ -0,0 +1,15 @@
+module Restapi
+  module Routing
+    module MapperExtensions
+      def restapi(route = "/apidoc")
+
+        Restapi.configuration.doc_base_url = route
+
+        self.get("#{route}/(:resource)/(:method)" => "restapis#index")
+
+      end
+    end
+  end
+end
+ 
+ActionDispatch::Routing::Mapper.send :include, Restapi::Routing::MapperExtensions

data/lib/restapi/validator.rb

@@ -0,0 +1,193 @@
+module Restapi
+  
+  module Validator
+    
+    # to create new validator, inherit from Restapi::Validator::Base
+    # and implement class method build and instance method validate
+    class BaseValidator
+
+      attr_accessor :param_name
+
+      # find the right validator for given options
+      def self.find(argument, options, block)
+        self.subclasses.each do |validator_type|
+          validator = validator_type.build(argument, options, block)
+          return validator if validator
+        end
+        return nil
+      end
+
+      # check if value is valid
+      def valid?(value)
+        if self.validate(value)
+          @error_value = nil
+          true
+        else
+          @error_value = value
+          false
+        end
+      end
+
+      # validator description
+      def description
+        "TODO: validator description"
+      end
+
+      def to_s
+        self.description
+      end
+
+      def to_json
+        self.description
+      end
+
+    end
+
+    # validate arguments type
+    class TypeValidator < BaseValidator
+
+      def initialize(argument)
+        @type = argument
+        @type = Integer if @type == Fixnum
+      end
+
+      def validate(value)
+        return false if value.nil?
+        begin
+          Kernel.send(@type.to_s, value)
+        rescue ArgumentError
+          return false
+        end
+      end
+
+      def self.build(argument, options, block)
+        self.new(argument) if argument.is_a?(Class) && argument != Hash
+      end
+
+      def error
+        "Parameter #{@param_name} expecting to be #{@type.name}, got: #{@error_value.class.name}"
+      end
+
+      def description
+        "Parameter has to be #{@type}."
+      end
+    end
+
+    # validate arguments value with regular expression
+    class RegexpValidator < BaseValidator
+
+      def initialize(argument)
+        @regexp = argument
+      end
+
+      def validate(value)
+        value =~ @regexp
+      end
+
+      def self.build(argument, options, proc)
+        self.new(argument) if argument.is_a? Regexp
+      end
+
+      def error
+        "Parameter #{@param_name} expecting to match /#{@regexp.source}/, got '#{@error_value}'"
+      end
+
+      def description
+        "Parameter has to match regular expression /#{@regexp.source}/."
+      end
+    end
+
+    # arguments value must be one of given in array
+    class ArrayValidator < BaseValidator
+
+      def initialize(argument)
+        @array = argument
+      end
+
+      def validate(value)
+
+        @array.find do |expected|
+          expected_class = expected.class
+          expected_class = Integer if expected_class == Fixnum
+          begin
+            converted_value = Kernel.send(expected_class.to_s, value)
+          rescue ArgumentError
+            false
+          end
+          converted_value === expected
+        end
+      end
+
+      def self.build(argument, options, proc)
+        self.new(argument) if argument.is_a?(Array)
+      end
+
+      def error
+        "Parameter #{@param_name} has bad value (#{@error_value.inspect}). Expecting one of: #{@array.join(',')}."
+      end
+
+      def description
+        "Parameter has to be one of: #{@array.join(', ')}."
+      end
+    end
+
+    class ProcValidator < BaseValidator
+
+      def initialize(argument)
+        @proc = argument
+      end
+
+      def validate(value)
+        (@help = @proc.call(value)) === true
+      end
+
+      def self.build(argument, options, proc)
+        self.new(argument) if argument.is_a?(Proc) && argument.arity == 1
+      end
+
+      def error
+        "Parameter #{@param_name} has bad value (\"#{@error_value}\"). #{@help}"
+      end
+
+      def description
+        ""
+      end
+    end
+
+    class HashValidator < BaseValidator
+
+      def self.build(argument, options, block)
+        self.new(block) if block.is_a?(Proc) && block.arity <= 0 && argument == Hash
+      end
+
+      def initialize(argument)
+        @proc = argument
+        @hash_params = {}
+
+        self.instance_exec(&@proc)
+      end
+      
+      def validate(value)
+        if @hash_params
+          @hash_params.each do |k, p|
+            p.validate(value[k]) if value.has_key?(k) || p.required
+          end
+        end
+        return true
+      end
+
+      def error
+        "TODO"
+      end
+
+      def description
+        "TODO"
+      end
+
+      def param(param_name, *args, &block)
+        @hash_params[param_name.to_sym] = Restapi::ParamDescription.new(param_name, *args, &block)
+      end
+    end
+
+  end
+end

data/lib/restapi/version.rb

@@ -0,0 +1,4 @@
+module Restapi
+  # gem version
+  VERSION = "0.0.1"
+end

data/restapi.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "restapi/version"
+
+Gem::Specification.new do |s|
+  s.name        = "restapi"
+  s.version     = Restapi::VERSION
+  s.authors     = ["Pavel Pokorny"]
+  s.email       = ["pajkycz@gmail.com"]
+  s.homepage    = "http://github.com/Pajk/restapi"
+  s.summary     = %q{REST API documentation tool}
+  s.description = %q{Maintain your API documentation up to date!}
+
+  s.rubyforge_project = "restapi"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec-rails"
+  s.add_development_dependency "rcov"
+  # s.add_runtime_dependency "rest-client"
+end

data/spec/controllers/restapis_controller_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe RestapisController do
+
+  describe "GET index" do
+
+    it "test if route exists" do
+      get :index
+
+      assert_response :success
+    end
+  end
+end

data/spec/controllers/users_controller_spec.rb

@@ -0,0 +1,175 @@
+require 'spec_helper'
+
+describe UsersController do
+  
+  describe "resource" do
+    it "should be described" do
+      a = Restapi.get_resource_description(UsersController)
+      
+      a._short_description.should eq('Site members')
+      # a._full_description.should eq("\n<h2 id=\"label-Long+description\">Long description</h2>\n\n<p>Example resource for rest api documentation</p>\n")
+      a._methods.should eq(["users#show", "users#create", "users#index"])
+      md = a._params[:id]
+      md.should_not be(nil)
+      md.name.should eq(:id)
+      md.desc.should eq("\n<p>User ID</p>\n")
+      md.required.should eq(true)
+      md.validator.class.should eq(Restapi::Validator::TypeValidator)
+      a._id.should eq('users')
+      a._path.should eq('/users')
+      a._version.should eq('1.0 - 3.4.2012')
+      a._name.should eq('Members')
+    end
+  end
+
+  describe "GET show" do
+
+    it "find a user with id" do
+      get :show, :id => 5, :session => "secret_hash"
+      
+      assert_response :success
+    end
+
+    it "throw ArgumentError if some required parameter missing" do
+      lambda { get :show, :id => 5 }.should raise_error(ArgumentError)
+    end
+    
+    it "responds with status 401 if session is wrong" do
+      get :show, :id => 5, :session => "bad_hash"
+      assert_response 401
+    end
+
+    it "should be annotated" do
+      
+      a = Restapi.get_method_description(UsersController, :show)
+      b = Restapi[UsersController, :show]
+      a.should eq(b)
+
+      a.method.should eq(:show)
+      a.resource.should eq('users')
+      a.errors[0].code.should eq(401)
+      a.errors[0].description.should eq("Unauthorized")
+      a.errors[1].code.should eq(404)
+      a.errors[1].description.should eq("Not Found")
+
+      a.short_description.should eq("Show user profile")
+      a.path.should eq("/users/:id")
+      a.http.should eq("GET")
+
+      param = a.params[:session]
+      param.required.should eq(true)
+      param.desc.should eq("\n<p>user is logged in</p>\n")
+      param.validator.class.should be(Restapi::Validator::TypeValidator)
+      param.validator.instance_variable_get("@type").should eq(String)
+      
+      param = a.params[:float_param]
+      param.required.should eq(false)
+      param.desc.should eq("\n<p>float param</p>\n")
+      param.validator.class.should be(Restapi::Validator::TypeValidator)
+      param.validator.instance_variable_get("@type").should eq(Float)
+
+      param = a.params[:id]
+      param.required.should eq(true)
+      param.desc.should eq("\n<p>user id</p>\n")
+      param.validator.class.should be(Restapi::Validator::TypeValidator)
+      param.validator.instance_variable_get("@type").should eq(Integer)
+
+      param = a.params[:regexp_param]
+      param.desc.should eq("\n<p>regexp param</p>\n")
+      param.required.should eq(false)
+      param.validator.class.should be(Restapi::Validator::RegexpValidator)
+      param.validator.instance_variable_get("@regexp").should eq(/^[0-9]* years/)
+
+      param = a.params[:array_param]
+      param.desc.should eq("\n<p>array validator</p>\n")
+      param.validator.class.should be(Restapi::Validator::ArrayValidator)
+      param.validator.instance_variable_get("@array").should eq([100, "one", "two", 1, 2])
+
+      param = a.params[:proc_param]
+      param.desc.should eq("\n<p>proc validator</p>\n")
+      param.validator.class.should be(Restapi::Validator::ProcValidator)
+      
+      a.full_description.length.should be > 400
+    end
+    
+    it "should yell ArgumentError if id is not a number" do
+      lambda { get :show, :id => "not a number", :session => "secret_hash" }.should raise_error(ArgumentError)
+    end
+    
+    it "should yell ArgumentError if float_param is not a float" do
+      lambda { get :show, :id => 5, :session => "secret_hash", :float_param => "234.2.34"}.should raise_error(ArgumentError)
+      lambda { get :show, :id => 5, :session => "secret_hash", :float_param => "no float here"}.should raise_error(ArgumentError)
+    end
+
+    it "should understand float validator" do
+      get :show, :id => 5, :session => "secret_hash", :float_param => "234.34"
+      assert_response :success
+      get :show, :id => 5, :session => "secret_hash", :float_param => "234"
+      assert_response :success
+    end
+    
+    it "should understand regexp validator" do
+      get :show, :id => 5, :session => "secret_hash", :regexp_param => "24 years"
+      assert_response :success
+    end
+    
+    it "should validate with regexp validator" do
+      lambda {
+        get :show, :id => 5, :session => "secret_hash", :regexp_param => "ten years"
+      }.should raise_error(ArgumentError)
+    end
+    
+    it "should validate with array validator" do
+      get :show, :id => 5, :session => "secret_hash", :array_param => "one"
+      assert_response :success
+      get :show, :id => 5, :session => "secret_hash", :array_param => "two"
+      assert_response :success
+      get :show, :id => 5, :session => "secret_hash", :array_param => 1
+      assert_response :success
+      get :show, :id => 5, :session => "secret_hash", :array_param => "2"
+      assert_response :success
+    end
+    
+    it "should raise ArgumentError with array validator" do
+      lambda { get :show, :id => 5, :session => "secret_hash", :array_param => "blabla" }.should
+      raise_error(ArgumentError)
+      
+      lambda { get :show, :id => 5, :session => "secret_hash", :array_param => 3 }.should
+      raise_error(ArgumentError)
+    end
+    
+    it "should validate with Proc validator" do
+      lambda { get :show, :id => 5, :session => "secret_hash", :proc_param => "asdgsag" }.should
+      raise_error(ArgumentError)
+      
+      get :show, :id => 5, :session => "secret_hash", :proc_param => "param value"
+      assert_response :success
+    end
+    
+  end
+
+  describe "POST create" do
+    
+    it "should understand hash validator" do
+      post :create, :user => { :username => "root", :password => "12345", :membership => "standard" }
+      assert_response :success
+
+      a = Restapi[UsersController, :create]
+      a.short_description.should eq("Create user")
+      a.path.should eq("/users")
+      a.http.should eq("POST")
+
+      lambda { post :create, :user => { :username => "root", :password => "12345", :membership => "____" } }.should
+      raise_error(ArgumentError)
+
+      lambda { post :create, :user => { :username => "root" } }.should
+      raise_error(ArgumentError)
+
+      post :create, :user => { :username => "root", :password => "pwd" }
+      assert_response :success
+
+    end
+
+  end
+
+end