restapi 0.0.4 → 0.0.5

data/lib/restapi/param_description.rb

@@ -1,7 +1,7 @@
 module Restapi
 
   # method parameter description
-  #
+  # 
   # name - method name (show)
   # desc - description
   # required - boolean if required
@@ -11,7 +11,7 @@ module Restapi
     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,15 +20,16 @@ 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

data/lib/restapi/railtie.rb

@@ -6,4 +6,4 @@ module Restapi
       end
     end
   end
-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}"
+      Restapi.full_url(@_id)
     end
 
     def api_url; "#{Restapi.configuration.api_base_url}#{@_path}"; end

data/lib/restapi/restapi_module.rb

@@ -29,6 +29,8 @@ module Restapi
     attr_accessor :app_name, :app_info, :copyright, :markup,
       :validate, :api_base_url, :doc_base_url
 
+    alias_method :validate?, :validate
+
     # matcher to be used in Dir.glob to find controllers to be reloaded e.g.
     #
     #   "#{Rails.root}/app/controllers/api/*.rb"
@@ -43,6 +45,47 @@ module Restapi
       @reload_controllers = Rails.env.development? unless defined? @reload_controllers
       return @reload_controllers && @api_controllers_matcher
     end
+
+    # set to true if you want to use pregenerated documentation cache and avoid
+    # generating the documentation on runtime (usefull for production
+    # environment).
+    # You can generate the cache by running
+    #
+    #     rake restapi:cache
+    attr_accessor :use_cache
+    alias_method :use_cache?, :use_cache
+
+    attr_writer :cache_dir
+    def cache_dir
+      @cache_dir ||= File.join(Rails.root, "public", "restapi-cache")
+    end
+
+    # if there is not obvious reason why the DSL should be turned on (no
+    # validations, cache turned on etc.), it's disabled to avoid unneeded
+    # allocation. It you need the DSL for other reasons, you can force the
+    # activation.
+    attr_writer :force_dsl
+    def force_dsl?
+      @force_dsl
+    end
+
+    # array of controller names (strings) (might include actions as well)
+    # to be ignored # when extracting description form calls.
+    # e.g. %w[Api::CommentsController Api::PostsController#post]
+    attr_writer :ignored_by_recorder
+    def ignored_by_recorder
+      @ignored_by_recorder ||= []
+      @ignored_by_recorder.map(&:to_s)
+    end
+
+    # comment to put before docs that was generated automatically. It's used to
+    # determine if the description should be overwritten next recording.
+    # If you want to keep the documentation (prevent from overriding), remove
+    # the line above the docs.
+    attr_writer :generated_doc_disclaimer
+    def generated_doc_disclaimer
+      @generated_doc_disclaimer ||= "# DOC GENERATED AUTOMATICALLY: REMOVE THIS LINE TO PREVENT REGENARATING NEXT TIME"
+    end
     
     def app_info
       Restapi.markup_to_html(@app_info)

data/lib/restapi/validator.rb

@@ -1,7 +1,8 @@
+# -*- coding: utf-8 -*-
 module Restapi
-  
+
   module Validator
-    
+
     # to create new validator, inherit from Restapi::Validator::Base
     # and implement class method build and instance method validate
     class BaseValidator
@@ -191,7 +192,7 @@ module Restapi
 
         self.instance_exec(&@proc)
       end
-      
+
       def validate(value)
         if @hash_params
           @hash_params.each do |k, p|
@@ -221,5 +222,71 @@ module Restapi
       end
     end
 
+
+    # special type of validator: we say that it's not specified
+    class UndefValidator < Restapi::Validator::BaseValidator
+
+      def validate(value)
+        true
+      end
+
+      def self.build(param_description, argument, options, block)
+        if argument == :undef
+          self.new(param_description)
+        end
+      end
+
+      def description
+        nil
+      end
+    end
+
+    class NumberValidator < Restapi::Validator::BaseValidator
+
+      def validate(value)
+        self.class.validate(value)
+      end
+
+      def self.build(param_description, argument, options, block)
+        if argument == :number
+          self.new(param_description)
+        end
+      end
+
+      def error
+        "Parameter #{param_name} expecting to be a number, got: #{@error_value}"
+      end
+
+      def description
+        "Has to be a number."
+      end
+
+      def self.validate(value)
+        value.to_s =~ /\A(0|[1-9]\d*)\Z$/
+      end
+    end
+
+    class BooleanValidator < Restapi::Validator::BaseValidator
+
+      def validate(value)
+        %w[true false].include?(value.to_s)
+      end
+
+      def self.build(param_description, argument, options, block)
+        if argument == :bool
+          self.new(param_description)
+        end
+      end
+
+      def error
+        "Parameter #{param_name} expecting to be a boolean value, got: #{@error_value}"
+      end
+
+      def description
+        "Has to be a boolean"
+      end
+    end
+
   end
 end
+

data/lib/restapi/version.rb

@@ -1,3 +1,3 @@
 module Restapi
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

data/lib/tasks/restapi.rake

@@ -1,157 +1,156 @@
+# -*- coding: utf-8 -*-
+require 'fileutils'
+require 'restapi/client/generator'
+
 namespace :restapi do
 
   desc "Generate static documentation"
+  # You can specify OUT=output_base_file to have the following structure:
+  #
+  #    output_base_file.html
+  #    output_base_file-onepage.html
+  #    output_base_file
+  #    | - resource1.html
+  #    | - resource1
+  #    | - | - method1.html
+  #    | - | - method2.html
+  #    | - resource2.html
+  #
+  # By default OUT="#{Rails.root}/doc/apidoc"
   task :static => :environment do
-
-    av = ActionView::Base.new(File.expand_path("../../../app/views", __FILE__))
-
-    av.class_eval do
-      include Restapi::RestapisHelper
+    with_loaded_documentation do
+      out = ENV["OUT"] || File.join(::Rails.root, 'doc', 'apidoc')
+      subdir = File.basename(out)
+
+      copy_jscss(out)
+
+      Restapi.url_prefix = "./#{subdir}"
+      doc = Restapi.to_json
+      generate_one_page(out, doc)
+      generate_plain_page(out, doc)
+      generate_index_page(out, doc)
+      Restapi.url_prefix = "../#{subdir}"
+      generate_resource_pages(out, doc)
+      Restapi.url_prefix = "../../#{subdir}"
+      generate_method_pages(out, doc)
     end
+  end
 
-    Dir[File.join(Rails.root, "app", "controllers", "**","*.rb")].each {|f| load f}
-
-    doc = Restapi.to_json()[:docs]
-
-    # dir in public directory
-    dir_path = File.join(::Rails.root.to_s, 'public', Restapi.configuration.doc_base_url)
-    FileUtils.rm_r(dir_path) if File.directory?(dir_path)
-    Dir.mkdir(dir_path)
+  desc "Generate cache to avoid production dependencies on markup languages"
+  task :cache => :environment do
+    with_loaded_documentation do
+      cache_dir = Restapi.configuration.cache_dir
+      file_base = File.join(cache_dir, Restapi.configuration.doc_base_url)
+      doc = Restapi.to_json
+      generate_index_page(file_base, doc, true)
+      generate_resource_pages(file_base, doc, true)
+      generate_method_pages(file_base, doc, true)
+    end
+  end
 
-    copy_jscss(File.join(dir_path, Restapi.configuration.doc_base_url))
+  def renderer
+    ActionView::Base.new(File.expand_path("../../../app/views/restapi/restapis", __FILE__))
+  end
 
-    Restapi.configuration.doc_base_url = Restapi.configuration.doc_base_url[1..-1]
-    File.open(File.join(dir_path,'index.html'), "w") do |f|
+  def render_page(file_name, template, variables, layout = 'restapi')
+    av = renderer
+    File.open(file_name, "w") do |f|
+      variables.each do |var, val|
+        av.instance_variable_set("@#{var}", val)
+      end
       f.write av.render(
-        :template => "restapi/restapis/static",
-        :locals => {:doc => doc},
-        :layout => 'layouts/restapi/restapi')
-      puts File.join(dir_path,'index.html')
+        :template => "#{template}",
+        :layout => (layout && "../../layouts/restapi/#{layout}"))
     end
-
   end
 
-  def copy_jscss(dest)
-    src = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'app', 'public', 'restapi'))
-    FileUtils.cp_r "#{src}/.", dest
-  end
+  def generate_one_page(file_base, doc)
+    FileUtils.mkdir_p(File.dirname(file_base)) unless File.exists?(File.dirname(file_base))
 
+    render_page("#{file_base}-onepage.html", "static", {:doc => doc[:docs]})
+  end
 
-  desc "Generate CLI client for API documented with restapi gem."
-  task :client, [:api_base_url, :url_append]  => [:environment] do |t, args|
+  def generate_plain_page(file_base, doc)
+    FileUtils.mkdir_p(File.dirname(file_base)) unless File.exists?(File.dirname(file_base))
 
-    args.with_defaults :api_base_url => 'http://localhost:3000', :url_append => ''
+    render_page("#{file_base}-plain.html", "plain", {:doc => doc[:docs]}, nil)
+  end
 
-    ActiveSupport::Dependencies.autoload_paths.each do |path|
-      Dir[path + "/*.rb"].each { |file| require file }
-    end
+  def generate_index_page(file_base, doc, include_json = false)
+    FileUtils.mkdir_p(File.dirname(file_base)) unless File.exists?(File.dirname(file_base))
 
-    Dir.mkdir('clients') unless File.exists?('clients')
+    render_page("#{file_base}.html", "index", {:doc => doc[:docs]})
 
-    doc = Restapi.to_json()[:docs]
+    File.open("#{file_base}.json", "w") { |f| f << doc.to_json } if include_json
+  end
 
-    create_base doc, args
+  def generate_resource_pages(file_base, doc, include_json = false)
+    doc[:docs][:resources].each do |resource_name, _|
+      resource_file_base = File.join(file_base, resource_name.to_s)
+      FileUtils.mkdir_p(File.dirname(resource_file_base)) unless File.exists?(File.dirname(resource_file_base))
 
-    create_cli doc
+      doc = Restapi.to_json(resource_name)
+      render_page("#{resource_file_base}.html", "resource", {:doc => doc[:docs],
+                                                          :resource => doc[:docs][:resources].first})
+      File.open("#{resource_file_base}.json", "w") { |f| f << doc.to_json } if include_json
+    end
   end
 
-  def ac(content, code, spaces = 0)
-    content << " "*spaces << code << "\n"
-  end
+  def generate_method_pages(file_base, doc, include_json = false)
+    doc[:docs][:resources].each do |resource_name, resource_params|
+      resource_params[:methods].each do |method|
+        method_file_base = File.join(file_base, resource_name.to_s, method[:name].to_s)
+        FileUtils.mkdir_p(File.dirname(method_file_base)) unless File.exists?(File.dirname(method_file_base))
 
-  def create_base doc, args
-    content = ""
-    ac content, "require 'rubygems'"
-    ac content, "require 'weary'"
-    ac content, "require 'thread' unless defined? Mutex\n"
-    ac content, "API_BASE_URL = ENV['API_URL'] || '#{args[:api_base_url]}'"
-    ac content, "URL_APPEND = ENV['URL_APPEND'] || '#{args[:url_append]}'\n"
-
-    doc[:resources].each do |key, resource|
-
-      ac content, "class #{key.camelize}Client < Weary::Client"
-      ac content, "domain API_BASE_URL", 2
-      resource[:methods].each do |method|
-        method[:apis].each do |api|
-          ac content, "# #{api[:short_description]}", 2
-          ac content, "#{api[:http_method].downcase} :#{method[:name]}, \"#{api[:api_url]}\#{URL_APPEND}\" do |resource|", 2
-          required = []
-          optional = []
-
-          method[:params].each do |param|
-            if param[:required]
-              required << param[:name].to_sym
-            else
-              optional << param[:name].to_sym
-            end
-          end
-          ac content, "resource.optional :#{optional.join(', :')}", 4 unless optional.blank?
-          ac content, "resource.required :#{required.join(', :')}", 4 unless required.blank?
-
-          ac content, "end", 2
-        end
+        doc = Restapi.to_json(resource_name, method[:name])
+        render_page("#{method_file_base}.html", "method", {:doc => doc[:docs],
+                                                           :resource => doc[:docs][:resources].first,
+                                                           :method => doc[:docs][:resources].first[:methods].first})
+
+        File.open("#{method_file_base}.json", "w") { |f| f << doc.to_json } if include_json
       end
-      ac content, "end\n"
     end
+  end
 
-    File.open('clients/base.rb', 'w') { |f| f.write content }
+  def with_loaded_documentation
+    Restapi.configuration.use_cache = false # we don't want to skip DSL evaluation
+    Dir[File.join(Rails.root, "app", "controllers", "**","*.rb")].each {|f| load f}
+    yield
+  end
+
+  def copy_jscss(dest)
+    src = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'app', 'public', 'restapi'))
+    FileUtils.mkdir_p dest
+    FileUtils.cp_r "#{src}/.", dest
   end
 
-  def create_cli doc
-
-    content = ""
-    ac content, "require 'rubygems'"
-    ac content, "require 'thor'"
-    ac content, "require './base'"
-
-    doc[:resources].each do |key, resource|
-      ac content, "class #{key.camelize} < Thor"
-        # ac content, "$klasses['#{key}'] = #{key.camelize}", 2
-        # ac content, "@client = RestClient::Resource.new \"\#{$API_URL}#{resource[:api_url]}\"\n", 2
-
-        ac content, "no_tasks do", 2
-        ac content, "  def client", 2
-        ac content, "    @client ||= #{key.camelize}Client.new", 2
-        ac content, "  end", 2
-        ac content, "end", 2
-
-        resource[:methods].each do |method|
-
-          method[:apis].each do |api|
-
-            params = []
-            method[:params].each do |param|
-              ac content, "method_option :#{param[:name]},", 2
-              ac content, ":required => #{param[:required] ? 'true' : 'false' },", 4
-              ac content, ":desc => '#{plaintext(param[:description])}',", 4
-              ac content, ":type => :#{param[:expected_type]}", 4
-              # :type — :string, :hash, :array, :numeric, or :boolean
-              params << param[:name]
-            end
-
-            ac content, "desc '#{method[:name]}', '#{api[:short_description]}'", 2
-            ac content, "def #{method[:name]}", 2
-            ac content, "  resp = client.#{method[:name]}(options).perform do |response|", 2
-            ac content, "    if response.success?", 2
-            ac content, "      puts response.body", 2
-            ac content, "    else", 2
-            ac content, "      puts \"status: \#{response.status}\"", 2
-            ac content, "      puts response.body", 2
-            ac content, "    end", 2
-            ac content, "  end", 2
-            ac content, "  resp.status", 2
-            ac content, "end\n", 2
-
-          end
 
-        end
-      ac content, "end\n"
-    end
+  desc "Generate CLI client for API documented with restapi gem."
+  task :client => [:environment] do |t, args|
+    Restapi.configuration.use_cache = false # we don't want to skip DSL evaluation
+    Restapi.api_controllers_paths.each { |file| require file }
 
-    File.open('clients/cli.thor', 'w') { |f| f.write content }
+    Restapi::Client::Generator.start(Restapi.configuration.app_name)
   end
 
   def plaintext(text)
     text.gsub(/<.*?>/, '').gsub("\n",' ').strip
   end
+
+  desc "Update api description in controllers base on routes"
+  task :update_from_routes => [:environment] do
+    Restapi.configuration.force_dsl = true
+    ignored = Restapi.configuration.ignored_by_recorder
+    with_loaded_documentation do
+      apis_from_routes = Restapi::Extractor.apis_from_routes
+      apis_from_routes.each do |(controller, action), apis|
+        next if ignored.include?(controller)
+        next if ignored.include?("#{controller}##{action}")
+        Restapi::Extractor::Writer.update_action_description(controller.constantize, action) do |u|
+          u.update_apis(apis)
+        end
+      end
+    end
+  end
+
 end