restapi 0.0.3 → 0.0.4

data/lib/restapi.rb

@@ -1,13 +1,3 @@
-require 'active_support/dependencies'
-
-# add path to restapi controller to ActiveSupport paths
-%w{ controllers views }.each do |dir|
-  path = File.join(File.dirname(__FILE__), 'app', dir)
-  $LOAD_PATH << path
-  ActiveSupport::Dependencies.autoload_paths << path
-  ActiveSupport::Dependencies.autoload_once_paths.delete(path)
-end
-
 require "restapi/routing"
 require "restapi/markup"
 require "restapi/restapi_module"

data/lib/restapi/application.rb

@@ -11,7 +11,7 @@ module Restapi
       end
     end
 
-    attr_accessor :last_api_args, :last_errors, :last_params, :last_description
+    attr_accessor :last_api_args, :last_errors, :last_params, :last_description, :last_examples
     attr_reader :method_descriptions, :resource_descriptions
     
     def initialize  
@@ -46,8 +46,12 @@ module Restapi
         Restapi::ResourceDescription.new(controller, resource_name, &block)
     end
 
-    def add_method_description_args(args)
-      @last_api_args << MethodDescription::Api.new(args)
+    def add_method_description_args(method, path, desc)
+      @last_api_args << MethodDescription::Api.new(method, path, desc)
+    end
+
+    def add_example(example)
+      @last_examples << example.strip_heredoc
     end
     
     # check if there is some saved description
@@ -94,6 +98,7 @@ module Restapi
       @last_errors = []
       @last_params = []
       @last_description = nil
+      @last_examples = []
     end
         
     # Return the current description, clearing it in the process.
@@ -120,6 +125,12 @@ module Restapi
       @last_params.clear
       params
     end
+
+    def get_examples
+      examples = @last_examples.clone
+      @last_examples.clear
+      examples
+    end
     
     def to_json(resource_name, method_name)
       
@@ -135,17 +146,21 @@ module Restapi
       end
 
       {
-        'docs' => {
-          'name' => Restapi.configuration.app_name,
-          'info' => Restapi.configuration.app_info,
-          'copyright' => Restapi.configuration.copyright,
-          'doc_url' => "#{ENV["RAILS_RELATIVE_URL_ROOT"]}#{Restapi.configuration.doc_base_url}",
-          'api_url' => Restapi.configuration.api_base_url,
-          'resources' => _resources
+        :docs => {
+          :name => Restapi.configuration.app_name,
+          :info => Restapi.configuration.app_info,
+          :copyright => Restapi.configuration.copyright,
+          :doc_url => "#{ENV["RAILS_RELATIVE_URL_ROOT"]}#{Restapi.configuration.doc_base_url}",
+          :api_url => Restapi.configuration.api_base_url,
+          :resources => _resources
         }
       }
     end
 
+    def reload_documentation
+      Dir[Restapi.configuration.api_controllers_matcher].each {|f|  load f}
+    end
+
     private
 
       def get_resource_name(klass)

data/lib/restapi/dsl_definition.rb

@@ -3,32 +3,30 @@
 module Restapi
 
   # DSL is a module that provides #api, #error, #param, #error.
-
   module DSL
 
     private
-    
+
     # Describe whole resource
-    # 
+    #
     # Example:
     # api :desc => "Show user profile", :path => "/users/", :version => '1.0 - 3.4.2012'
     # param :id, Fixnum, :desc => "User ID", :required => true
     # desc <<-EOS
     #   Long description...
     # EOS
-    def resource_description(options = {}, &block)
+    def resource_description(options = {}, &block) #:doc:
+      Restapi.remove_resource_description(self)
       Restapi.define_resource_description(self, &block) if block_given?
     end
 
     # Declare an api.
     #
     # Example:
-    #   api :desc => "short description",
-    #       :path => "/resource_route",
-    #       :method => "GET"
+    #   api :GET, "/resource_route", "short description",
     #
-    def api(args)
-      Restapi.add_method_description_args(args)
+    def api(method, path, desc = nil) #:doc:
+      Restapi.add_method_description_args(method, path, desc)
     end
 
     # Describe the next method.
@@ -39,7 +37,7 @@ module Restapi
     #     puts "hello world"
     #   end
     #
-    def desc(description)
+    def desc(description) #:doc:
       if Restapi.last_description
         raise "Double method description."
       end
@@ -47,6 +45,12 @@ module Restapi
     end
     alias :description :desc
 
+    # Show some example of what does the described
+    # method return.
+    def example(example) #:doc:
+      Restapi.add_example(example)
+    end
+
     # Describe possible errors
     #
     # Example:
@@ -56,10 +60,10 @@ module Restapi
     #     puts "hello world"
     #   end
     #
-    def error(args)
+    def error(args) #:doc:
       Restapi.last_errors << Restapi::ErrorDescription.new(args)
     end
-    
+
     # Describe method's parameter
     #
     # Example:
@@ -68,17 +72,17 @@ module Restapi
     #     puts greeting
     #   end
     #
-    def param(param_name, *args, &block)
+    def param(param_name, *args, &block) #:doc:
       Restapi.last_params << Restapi::ParamDescription.new(param_name, *args, &block)
     end
-    
+
     # create method api and redefine newly added method
-    def method_added(method_name)
+    def method_added(method_name) #:doc:
 
       super
-      
+
       return unless Restapi.restapi_provided?
-      
+
       # remove method description if exists and create new one
       Restapi.remove_method_description(self, method_name)
       description = Restapi.define_method_description(self, method_name)
@@ -86,30 +90,32 @@ module Restapi
       # redefine method only if validation is turned on
       if Restapi.configuration.validate == true
 
-        old_method = instance_method(method_name) 
-        
+        old_method = instance_method(method_name)
+
         define_method(method_name) do |*args|
-          
-          description.params.each do |_, param|
 
-            # check if required parameters are present
-            if param.required && !params.has_key?(param.name)
-              raise ArgumentError.new("Expecting #{param.name} parameter.")
-            end
-            
-            # params validations
-            if params.has_key?(param.name)
-              param.validate(params[:"#{param.name}"])
-            end
+          if Restapi.configuration.validate == true
+            description.params.each do |_, param|
 
-          end # params.each
+              # check if required parameters are present
+              if param.required && !params.has_key?(param.name)
+                raise ArgumentError.new("Expecting #{param.name} parameter.")
+              end
+
+              # params validations
+              if params.has_key?(param.name)
+                param.validate(params[:"#{param.name}"])
+              end
+
+            end
+          end
 
           # run the original method code
           old_method.bind(self).call(*args)
         end
 
       end
-      
+
     end # def method_added
   end # module DSL
 end # module Restapi

data/lib/restapi/markup.rb

@@ -1,40 +1,40 @@
 module Restapi
-  
+
   module Markup
-    
+
     class RDoc
-      
+
       def initialize
         require 'rdoc'
         require 'rdoc/markup/to_html'
         @rdoc ||= ::RDoc::Markup::ToHtml.new
       end
-      
+
       def to_html(text)
         @rdoc.convert(text)
       end
-      
+
     end
-    
+
     class Markdown
-      
+
       def initialize
         require 'redcarpet'
         @redcarpet ||= ::Redcarpet::Markdown.new(::Redcarpet::Render::HTML.new)
       end
-      
+
       def to_html(text)
         @redcarpet.render(text)
       end
-      
+
     end
-    
+
     class Textile
-      
+
       def initialize
         require 'RedCloth'
       end
-      
+
       def to_html(text)
         RedCloth.new(text).to_html
       end

data/lib/restapi/method_description.rb

@@ -7,10 +7,10 @@ module Restapi
       
       attr_accessor :short_description, :api_url, :http_method
       
-      def initialize(args)
-        @http_method = args[:method] || args[:http_method] || args[:http]
-        @short_description = args[:desc] || args[:short] || args[:description]
-        @api_url = create_api_url(args[:path] || args[:url])
+      def initialize(method, path, desc)
+        @http_method = method.to_s
+        @api_url = create_api_url(path)
+        @short_description = desc
       end
       
       private
@@ -21,7 +21,7 @@ module Restapi
 
     end
 
-    attr_reader :errors, :full_description, :method, :resource, :apis
+    attr_reader :errors, :full_description, :method, :resource, :apis, :examples
     
     def initialize(method, resource, app)
       @method = method
@@ -33,6 +33,7 @@ module Restapi
       @full_description = Restapi.markup_to_html(desc)
       @errors = app.get_errors
       @params_ordered = app.get_params
+      @examples = app.get_examples
 
       parent = @resource.controller.superclass
       if parent != ActionController::Base
@@ -66,7 +67,7 @@ module Restapi
       [
         ENV["RAILS_RELATIVE_URL_ROOT"],
         Restapi.configuration.doc_base_url,
-        "##{@resource._id}/#{@method}"
+        "/#{@resource._id}/#{@method}"
       ].join
     end
 
@@ -74,7 +75,7 @@ module Restapi
       @apis.each.collect do |api|
         {
           :api_url => api.api_url,
-          :http_method => api.http_method,
+          :http_method => api.http_method.to_s,
           :short_description => api.short_description
         }
       end
@@ -87,7 +88,8 @@ module Restapi
         :apis => method_apis_to_json,
         :full_description => @full_description,
         :errors => @errors,
-        :params => params_ordered.map(&:to_json).flatten
+        :params => params_ordered.map(&:to_json).flatten,
+        :examples => @examples
       }
     end
 

data/lib/restapi/param_description.rb

@@ -1,17 +1,17 @@
 module Restapi
 
   # method parameter description
-  # 
+  #
   # name - method name (show)
   # desc - description
   # required - boolean if required
   # validator - Validator::BaseValidator subclass
   class ParamDescription
 
-    attr_reader :name, :desc, :required, :validator
+    attr_reader :name, :desc, :required, :allow_nil, :validator
 
     attr_accessor :parent
-    
+
     def initialize(name, *args, &block)
 
       if args.size > 1 || !args.first.is_a?(Hash)
@@ -20,20 +20,21 @@ module Restapi
         validator_type = nil
       end
       options = args.pop || {}
-      
+
       @name = name
       @desc = Restapi.markup_to_html(options[:desc] || '')
       @required = options[:required] || false
-      
+      @allow_nil = options[:allow_nil] || false
+
       @validator = nil
       unless validator_type.nil?
-        @validator = 
-          Validator::BaseValidator.find(self, validator_type, options, block)
+        @validator = Validator::BaseValidator.find(self, validator_type, options, block)
         raise "Validator not found." unless validator
       end
     end
 
     def validate(value)
+      return true if @allow_nil && value.nil?
       unless @validator.valid?(value)
         raise ArgumentError.new(@validator.error)
       end
@@ -57,13 +58,25 @@ module Restapi
 
     def to_json
       if validator.is_a? Restapi::Validator::HashValidator
-        validator.hash_params_ordered.map(&:to_json)
+        {
+          :name => name.to_s,
+          :full_name => full_name,
+          :description => desc,
+          :required => required,
+          :allow_nil => allow_nil,
+          :validator => validator.to_s,
+          :expected_type => validator.expected_type,
+          :params => validator.hash_params_ordered.map(&:to_json)
+        }
       else
         {
-          :name => full_name,
+          :name => name.to_s,
+          :full_name => full_name,
           :description => desc,
           :required => required,
-          :validator => validator.to_s
+          :allow_nil => allow_nil,
+          :validator => validator.to_s,
+          :expected_type => validator.expected_type
         }
       end
     end

data/lib/restapi/resource_description.rb

@@ -56,7 +56,7 @@ module Restapi
     end
     
     def doc_url
-      "#{ENV["RAILS_RELATIVE_URL_ROOT"]}#{Restapi.configuration.doc_base_url}##{@_id}"
+      "#{ENV["RAILS_RELATIVE_URL_ROOT"]}#{Restapi.configuration.doc_base_url}/#{@_id}"
     end
 
     def api_url; "#{Restapi.configuration.api_base_url}#{@_path}"; end

data/lib/restapi/restapi_module.rb

@@ -28,6 +28,21 @@ module Restapi
   class Configuration
     attr_accessor :app_name, :app_info, :copyright, :markup,
       :validate, :api_base_url, :doc_base_url
+
+    # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
+    #
+    #   "#{Rails.root}/app/controllers/api/*.rb"
+    attr_accessor :api_controllers_matcher
+
+    # set to true if you want to reload the controllers at each refresh of the
+    # documentation. It requires +:api_controllers_matcher+ to be set to work
+    # properly.
+    attr_writer :reload_controllers
+
+    def reload_controllers?
+      @reload_controllers = Rails.env.development? unless defined? @reload_controllers
+      return @reload_controllers && @api_controllers_matcher
+    end
     
     def app_info
       Restapi.markup_to_html(@app_info)