apipie-rails 0.0.13 → 0.0.14

data/README.rdoc

@@ -1,367 +0,0 @@
-= API Documentation Tool {<img src="https://secure.travis-ci.org/Pajk/apipie-rails.png?branch=master" alt="Build Status" />}[http://travis-ci.org/Pajk/apipie-rails]
-
-== What?
-
-Every API needs a documentation otherwise no one know how to use it.
-It is not easy to maintain such documentation always up to date if it
-develops over time. Additionaly to this most programmers don't like writing
-documentation and so it could happen that your API is useless because
-of outdated documentation. If the documentation is just text completely
-separated from code then there is no simple way to verify its correctness.
-
-This gem adds some new methods to Rails controllers that can be used
-to describe resources which are exposed by our API. It is meant to
-be used for {RESTful}[http://cs.wikipedia.org/wiki/Representational_State_Transfer]
-web services and because we are talking about Rails you probably know
-what it is all about.
-
-Informations you entered with provided DSL are used to generate
-online documentation and validate values of incoming requests parameters.
-
-== Why?
-
-Documentation will be closer to your code and thus less prone to become
-obsolete. You get documentation frontend without effort. And if you want your
-own design you can do it anytime because json API for your API documentation
-is provided. There are no limits on how to use those informations, the
-builtin web interface is only one of possible options.
-
-Request parameters will be validated before they will get in touch with yours
-controller action or model code. And you inform API users about expected
-parameters values. This information will be always actual because otherwise
-your tests fail (of course you have tests!).
-
-This is how the web interface look like. Try it live on
-http://restapi-likes.rhcloud.com. Example users resource
-description are taken from Twitter(c) API.
-
-https://img.skitch.com/20120428-nruk3e87xs2cu4ydsjujdh11fq.png
-
-https://img.skitch.com/20120428-bni2cmq5cyhjuw1jkd78e3qjxn.png
-
-== How?
-
-=== Gemfile
-
-Add +apipie+ gem to your gemfile and run bundle.
-
-    gem 'apipie-rails'
-
-For bleeding edge version use GitHub version
-
-    gem 'apipie-rails', :git => 'git://github.com/Pajk/apipie-rails.git'
-
-=== Config file
-
-Create configuration file in e.g. */config/initializers/apipie.rb*.
-You can set  application name, footer text, API and documentation base URL
-and turn off validations. You can also choose your favorite markup language
-of full descriptions.
-
-[app_name] Name of your application used in breadcrumbs navigation.
-[copyright] Copyright information (shown in page footer).
-[doc_base_url] Documentation frontend base url.
-[api_base_url] Base url of your API, most probably /api.
-[validate] Parameters validation is turned off when set to false.
-[app_info] Application long description.
-[reload_controllers] Set to enable/disable reloading controllers (and the documentation with it), by default enabled in development.
-[api_controllers_matcher] For reloading to work properly you need to specify where your API controllers are.
-[markup] You can choose markup language for descriptions of your application,
-         resources and methods. RDoc is the default but you can choose from
-         Apipie::Markup::Markdown.new or Apipie::Markup::Textile.new.
-         In order to use Markdown you need Redcarpet gem and for Textile you
-         need RedCloth. Add those to your gemfile and run bundle if you
-         want to use them. You can also add any other markup language
-         processor.
-[layout] Name of a layout template to use instead of Apipie's layout. You can use Apipie.include_stylesheets and Apipie.include_javascripts helpers to include Apipie's stylesheets and javascripts.
-
-Example:
-
-    Apipie.configure do |config|
-      config.app_name = "Test app"
-      config.copyright = "&copy; 2012 Pavel Pokorny"
-      config.doc_base_url = "/apidoc"
-      config.api_base_url = "/api"
-      config.validate = false
-      config.markup = Apipie::Markup::Markdown.new
-      config.reload_controllers = true
-      config.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
-      config.app_info = <<-DOC
-        This is where you can inform user about your application and API
-        in general.
-      DOC
-    end
-
-=== Routes
-
-Add +apipie+ to your *routes.rb*, that's all.
-
-
-=== Resource Description
-
-Resource can be described in corresponding controller by calling +resource_description+ method with block. Parameters described here are used
-for every method unless they are overridden with NilValidator.
-Parameters are inherited in controller hierarchy. So for example you can define
-in base ApplicationController parameters for authentication and they will
-be checked in every request.
-
-[name] You can force resource to display under some alias.
-[short] One line short description.
-[path] Relative URL path of this resource.
-[version] Version of this resource API, use arbitrary string.
-[formats] Resource level request / response formats.
-[param] The very same parameter description as you will use method
-        description. Generally use this for parameters that apply
-        to every method in the controller (such as :user hash).
-        It is possible to hide it for individual methods by setting
-        it's validator to nil.
-[description] The full multiline description of the resource and
-              yours API options
-
-Example:
-
-    class UsersController < ApplicationController
-
-      resource_description do
-        name 'Members'
-        short 'Site members'
-        path '/users'
-        version '1.0 - 3.4.2012'
-        formats ['json', 'xml']
-        param :id, Fixnum, :desc => "User ID", :required => false
-        param :user, Hash, :desc => 'Param description for all methods' do
-          param :username, String, :required => true,
-                :desc => "Username for login"
-          param :password, String, :required => true,
-                :desc => "Password for login"
-        end
-        description <<-DOC
-          Full description of this resource.
-        DOC
-      end
-      #...
-    end
-
-
-=== Method Description
-
-Then describe methods available to your API.
-
-[api] Say how is this method exposed and provide short description.
-      The first parameter is HTTP method (one of :GET/:POST/:PUT/:DELETE).
-      The second parameter is relative URL path which is mapped to this
-      method. The last parameter is methods short description.
-      You can use this +api+ method more than once for one method. It could
-      be useful when there are more routes mapped to it.
-[param] Look at Parameter description section for details.
-[formats] Method level request / response formats.
-[error] Describe each possible error that can happend what calling this
-        method. HTTP response code and description can be provided.
-[description] Full method description which will be converted to HTML by
-              choosen markup language processor.
-[example] Provide example of server response, whole communication or response type.
-          It will be formatted as code.
-[see] Provide reference to another method, this has to be string with
-      controller_name#method_name. 
-
-Example:
-
-   api :GET, "/users/:id", "Show user profile"
-   error :code => 401, :desc => "Unauthorized"
-   error :code => 404, :desc => "Not Found"
-   param :session, String, :desc => "user is logged in", :required => true
-   param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
-   param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
-   param :boolean_param, [true, false], :desc => "array validator with boolean"
-   param :proc_param, lambda { |val|
-     val == "param value" ? true : "The only good value is 'param value'."
-   }, :desc => "proc validator"
-   description "method description"
-   formats ['json', 'jsonp', 'xml']
-   example " 'user': {...} "
-   see "users#showme"
-   def show
-     #...
-   end
-
-== Parameter Description
-
-Use +param+ to describe every possible parameter. You can use Hash validator
-in cooperation with block given to param method to describe nested parameters.
-
-[name] The first argument is parameter name as a symbol.
-[validator] Second parameter is parameter validator, choose one from section
-            Validators.
-[desc] Parameter description.
-[required] Set this true/false to make it required/optional.
-           Default is optional
-
-Example:
-
-    param :user, Hash, :desc => "User info" do
-      param :username, String, :desc => "Username for login", :required => true
-      param :password, String, :desc => "Password for login", :required => true
-      param :membership, ["standard","premium"], :desc => "User membership"
-    end
-    def create
-      #...
-    end
-
-
-== Validators
-
-Every parameter needs to have associated validator. For now there are some
-basic validators. You can always provide your own to reach complex
-results.
-If validations are enabled (default state) the parameters of every
-request are validated. If the value is wrong a +ArgumentError+ exception
-is raised and can be rescued and processed. It contains some description
-of parameter value expectations. Validations can be turned off
-in configuration file.
-
-=== TypeValidator
-
-Check the parameter type. Only String, Hash and Array are supported
-for the sake of simplicity. Read more to to find out how to add
-your own validator.
-
-    param :session, String, :desc => "user is logged in", :required => true
-    param :facts, Hash, :desc => "Additional optional facts about the user"
-
-=== RegexpValidator
-
-Check parameter value against given regular expression.
-
-    param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
-
-=== ArrayValidator
-
-Check if parameter value is included given array.
-
-    param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
-
-=== ProcValidator
-
-If you need more complex validation and you know you won't reuse it you
-can use Proc/lambda validator. Provide your own Proc taking value
-of parameter as the only argument. Return true if value pass validation
-or return some text about what is wrong. _Don't use the keyword *return*
-if you provide instance of Proc (with lambda it is ok), just use the last
-statement return property of ruby_.
-
-    param :proc_param, lambda { |val|
-      val == "param value" ? true : "The only good value is 'param value'."
-    }, :desc => "proc validator"
-
-=== HashValidator
-
-You can describe hash parameters in depth if you provide a block with
-description of nested values.
-
-    param :user, Hash, :desc => "User info" do
-      param :username, String, :desc => "Username for login", :required => true
-      param :password, String, :desc => "Password for login", :required => true
-      param :membership, ["standard","premium"], :desc => "User membership"
-    end
-
-=== NilValidator
-
-In fact there is any NilValidator but setting it to nil can be used to
-override parameters described on resource level.
-
-Example:
-
-    param :user, nil
-    def destroy
-      #...
-    end
-
-=== Adding custom validator
-
-Only basic validators are included but it is really easy to add your own.
-Create new initializer with subclass of Apipie::Validator::BaseValidator.
-Two methods are required to implement - instance method
-<tt>validate(value)</tt> and class method
-<tt>build(param_description, argument, options, block)</tt>.
-
-When searching for validator +build+ method of every subclass of
-Apipie::Validator::BaseValidator is called. The first one whitch return
-constructed validator object is used.
-
-Example: Adding IntegerValidator
-
-We want to check if parameter value is an integer like this:
-
-    param :id, Integer, :desc => "Company ID"
-
-So we create apipie_validators.rb initializer with this content:
-
-    class IntegerValidator < Apipie::Validator::BaseValidator
-
-      def initialize(param_description, argument)
-        super(param_description)
-        @type = argument
-      end
-
-      def validate(value)
-        return false if value.nil?
-        !!(value.to_s =~ /^[-+]?[0-9]+$/)
-      end
-
-      def self.build(param_description, argument, options, block)
-        if argument == Integer || argument == Fixnum
-          self.new(param_description, argument)
-        end
-      end
-
-      def description
-        "Must be #{@type}."
-      end
-    end
-
-Parameters of the build method:
-
-[param_description] Instance of Apipie::ParamDescription contains all
-                    given informations about validated parameter.
-[argument] Specified validator, in our example it is +Integer+
-[options] Hash with specified options, for us just
-          <tt>{:desc => "Company ID"}</tt>
-[block] Block converted into Proc, use it as you desire. In this example nil.
-
-
-== Markup
-
-The default markup language is {RDoc}[http://rdoc.rubyforge.org/RDoc/Markup.html]. It can be changed in
-config file (config.markup=) to one of these:
-[Markdown] Use Apipie::Markup::Markdown.new. You need Redcarpet gem.
-[Textile] Use Apipie::Markup::Textile.new. You need RedCloth gem.
-
-Or provide you own object with <tt>to_html(text)</tt> method.
-For inspiration this is how Textile look like:
-
-    class Textile
-      def initialize
-        require 'RedCloth'
-      end
-      def to_html(text)
-        RedCloth.new(text).to_html
-      end
-    end
-
-== Static page
-
-To generate static version of documentation run <tt>rake apipie:static</tt> task.
-It will create folder with one-page documentation in your public directory. Rename
-or delete it if you want to use 'normal' dynamic version again.
-
-== {CLI client}[https://github.com/Pajk/apipie-rails/wiki/CLI-client]
-
-== {Extractor}[https://github.com/Pajk/apipie-rails/wiki/Extractor]
-
-== Authors
-
-{Pajk}[https://github.com/Pajk] and {iNecas}[https://github.com/iNecas]
-
-== Contributors
-
-See {Contributors page}[https://github.com/Pajk/apipie-rails/graphs/contributors]. Special thanks to all of them!

data/lib/apipie/client/base.rb

@@ -1,133 +0,0 @@
-require 'rest_client'
-require 'oauth'
-require 'json'
-require 'apipie/client/rest_client_oauth'
-
-module Apipie
-  module Client
-
-    class Base
-      attr_reader :client, :config
-
-      def initialize(config, options = { })
-        @client = RestClient::Resource.new config[:base_url],
-                                           :user     => config[:username],
-                                           :password => config[:password],
-                                           :oauth    => config[:oauth],
-                                           :headers  => { :content_type => 'application/json',
-                                                          :accept       => 'application/json' }
-        @config = config
-      end
-
-      def call(method, path, params = { }, headers = { })
-        headers ||= { }
-
-        args = [method]
-        if [:post, :put].include?(method)
-          args << params.to_json
-        else
-          headers[:params] = params if params
-        end
-
-        args << headers if headers
-        process_data client[path].send(*args)
-      end
-
-      def self.doc
-        raise NotImplementedError
-      end
-
-      def self.validation_hash(method)
-        validation_hashes[method.to_s]
-      end
-
-      def self.method_doc(method)
-        method_docs[method.to_s]
-      end
-
-      def validate_params!(params, rules)
-        return unless params.is_a?(Hash)
-
-        invalid_keys = params.keys.map(&:to_s) - (rules.is_a?(Hash) ? rules.keys : rules)
-        raise ArgumentError, "Invalid keys: #{invalid_keys.join(", ")}" unless invalid_keys.empty?
-
-        if rules.is_a? Hash
-          rules.each do |key, sub_keys|
-            validate_params!(params[key], sub_keys) if params[key]
-          end
-        end
-      end
-
-      protected
-
-      def process_data(response)
-        data = begin
-          JSON.parse(response.body)
-        rescue JSON::ParserError
-          response.body
-        end
-        return data, response
-      end
-
-      def check_params(params, options = { })
-        raise ArgumentError unless (method = options[:method])
-        return unless config[:enable_validations]
-
-        case options[:allowed]
-          when true
-            validate_params!(params, self.class.validation_hash(method))
-          when false
-            raise ArgumentError, "this method '#{method}' does not support params" if params && !params.empty?
-          else
-            raise ArgumentError, "options :allowed should be true or false, it was #{options[:allowed]}"
-        end
-      end
-
-      # @return url and rest of the params
-      def fill_params_in_url(url, params)
-        params          ||= { }
-        # insert param values
-        url_param_names = params_in_path(url)
-        url             = params_in_path(url).inject(url) do |url, param_name|
-          param_value = params[param_name] or
-              raise ArgumentError, "missing param '#{param_name}' in parameters"
-          url.sub(":#{param_name}", param_value.to_s)
-        end
-
-        return url, params.reject { |param_name, _| url_param_names.include? param_name }
-      end
-
-      private
-
-      def self.method_docs
-        @method_docs ||= doc['methods'].inject({ }) do |hash, method|
-          hash[method['name']] = method
-          hash
-        end
-      end
-
-      def self.validation_hashes
-        @validation_hashes ||= method_docs.inject({ }) do |hash, pair|
-          name, method_doc = pair
-          hash[name]       = construct_validation_hash method_doc
-          hash
-        end
-      end
-
-      def self.construct_validation_hash(method)
-        if method['params'].any? { |p| p['params'] }
-          method['params'].reduce({ }) do |h, p|
-            h.update(p['name'] => (p['params'] ? p['params'].map { |pp| pp['name'] } : nil))
-          end
-        else
-          method['params'].map { |p| p['name'] }
-        end
-      end
-
-      def params_in_path(url)
-        url.scan(/:([^\/]*)/).map { |m| m.first }
-      end
-
-    end
-  end
-end