apipie-rails 0.0.7

data/lib/apipie/validator.rb

@@ -0,0 +1,292 @@
+# -*- coding: utf-8 -*-
+module Apipie
+
+  module Validator
+
+    # to create new validator, inherit from Apipie::Validator::Base
+    # and implement class method build and instance method validate
+    class BaseValidator
+
+      attr_accessor :param_description
+
+      def initialize(param_description)
+        @param_description = param_description
+      end
+
+      def self.inherited(subclass)
+        @validators ||= []
+        @validators.insert 0, subclass
+      end
+
+      # find the right validator for given options
+      def self.find(param_description, argument, options, block)
+        @validators.each do |validator_type|
+          validator = validator_type.build(param_description, 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
+
+      def param_name
+        @param_description.name
+      end
+
+      # validator description
+      def description
+        "TODO: validator description"
+      end
+
+      def to_s
+        self.description
+      end
+
+      def to_json
+        self.description
+      end
+
+      # what type is expected, mostly string
+      # this information is used in cli client
+      # thor supported types — :string, :hash, :array, :numeric, or :boolean
+      def expected_type
+        'string'
+      end
+
+    end
+
+    # validate arguments type
+    class TypeValidator < BaseValidator
+
+      def initialize(param_description, argument)
+        super(param_description)
+        @type = argument
+      end
+
+      def validate(value)
+        return false if value.nil?
+        value.is_a? @type
+      end
+
+      def self.build(param_description, argument, options, block)
+        if argument.is_a?(Class) && (argument != Hash || block.nil?)
+          self.new(param_description, argument)
+        end
+      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
+
+      def expected_type
+        if @type.ancestors.include? Hash
+          'hash'
+        elsif @type.ancestors.include? Numeric
+          'numeric'
+        else
+          'string'
+        end
+      end
+    end
+
+    # validate arguments value with regular expression
+    class RegexpValidator < BaseValidator
+
+      def initialize(param_description, argument)
+        super(param_description)
+        @regexp = argument
+      end
+
+      def validate(value)
+        value =~ @regexp
+      end
+
+      def self.build(param_description, argument, options, proc)
+        self.new(param_description, 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(param_description, argument)
+        super(param_description)
+        @array = argument
+      end
+
+      def validate(value)
+        @array.include?(value)
+      end
+
+      def self.build(param_description, argument, options, proc)
+        self.new(param_description, 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(param_description, argument)
+        super(param_description)
+        @proc = argument
+      end
+
+      def validate(value)
+        (@help = @proc.call(value)) === true
+      end
+
+      def self.build(param_description, argument, options, proc)
+        self.new(param_description, 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
+
+      attr_reader :hash_params_ordered
+
+      def self.build(param_description, argument, options, block)
+        self.new(param_description, block) if block.is_a?(Proc) && block.arity <= 0 && argument == Hash
+      end
+
+      def initialize(param_description, argument)
+        super(param_description)
+        @proc = argument
+        @hash_params_ordered = []
+        @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
+        "Has to be hash."
+      end
+
+      def description
+        "Has to be hash."
+      end
+
+      def param(param_name, *args, &block)
+        param_description = Apipie::ParamDescription.new(param_name, *args, &block)
+        param_description.parent = self.param_description
+        @hash_params_ordered << param_description
+        @hash_params[param_name.to_sym] = param_description
+      end
+
+      def expected_type
+        'hash'
+      end
+    end
+
+
+    # special type of validator: we say that it's not specified
+    class UndefValidator < Apipie::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 < Apipie::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 < Apipie::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/apipie/version.rb

@@ -0,0 +1,3 @@
+module Apipie
+  VERSION = '0.0.7'
+end

data/lib/tasks/apipie.rake

@@ -0,0 +1,156 @@
+# -*- coding: utf-8 -*-
+require 'fileutils'
+require 'apipie/client/generator'
+
+namespace :apipie 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
+    with_loaded_documentation do
+      out = ENV["OUT"] || File.join(::Rails.root, 'doc', 'apidoc')
+      subdir = File.basename(out)
+
+      copy_jscss(out)
+
+      Apipie.url_prefix = "./#{subdir}"
+      doc = Apipie.to_json
+      generate_one_page(out, doc)
+      generate_plain_page(out, doc)
+      generate_index_page(out, doc)
+      Apipie.url_prefix = "../#{subdir}"
+      generate_resource_pages(out, doc)
+      Apipie.url_prefix = "../../#{subdir}"
+      generate_method_pages(out, doc)
+    end
+  end
+
+  desc "Generate cache to avoid production dependencies on markup languages"
+  task :cache => :environment do
+    with_loaded_documentation do
+      cache_dir = Apipie.configuration.cache_dir
+      file_base = File.join(cache_dir, Apipie.configuration.doc_base_url)
+      doc = Apipie.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
+
+  def renderer
+    ActionView::Base.new(File.expand_path("../../../app/views/apipie/apipies", __FILE__))
+  end
+
+  def render_page(file_name, template, variables, layout = 'apipie')
+    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 => "#{template}",
+        :layout => (layout && "../../layouts/apipie/#{layout}"))
+    end
+  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
+
+  def generate_plain_page(file_base, doc)
+    FileUtils.mkdir_p(File.dirname(file_base)) unless File.exists?(File.dirname(file_base))
+
+    render_page("#{file_base}-plain.html", "plain", {:doc => doc[:docs]}, nil)
+  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))
+
+    render_page("#{file_base}.html", "index", {:doc => doc[:docs]})
+
+    File.open("#{file_base}.json", "w") { |f| f << doc.to_json } if include_json
+  end
+
+  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))
+
+      doc = Apipie.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 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))
+
+        doc = Apipie.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
+    end
+  end
+
+  def with_loaded_documentation
+    Apipie.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', 'apipie'))
+    FileUtils.mkdir_p dest
+    FileUtils.cp_r "#{src}/.", dest
+  end
+
+
+  desc "Generate CLI client for API documented with apipie gem."
+  task :client => [:environment] do |t, args|
+    Apipie.configuration.use_cache = false # we don't want to skip DSL evaluation
+    Apipie.api_controllers_paths.each { |file| require file }
+
+    Apipie::Client::Generator.start(Apipie.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
+    Apipie.configuration.force_dsl = true
+    ignored = Apipie.configuration.ignored_by_recorder
+    with_loaded_documentation do
+      apis_from_routes = Apipie::Extractor.apis_from_routes
+      apis_from_routes.each do |(controller, action), apis|
+        next if ignored.include?(controller)
+        next if ignored.include?("#{controller}##{action}")
+        Apipie::Extractor::Writer.update_action_description(controller.constantize, action) do |u|
+          u.update_apis(apis)
+        end
+      end
+    end
+  end
+
+end