restapi 0.0.3 → 0.0.4

data/Gemfile

@@ -1,6 +1,6 @@
 source "http://rubygems.org"
 
-gem "rails", "3.0.11"
+gem "rails", ">= 3.0.11"
 gem "sqlite3"
 
 group :development, :test do
@@ -9,4 +9,5 @@ group :development, :test do
   gem "redcarpet"
   gem "RedCloth"
   gem "rake"
+  gem "weary", ">= 1.0.1"
 end

data/Gemfile.lock

@@ -2,97 +2,116 @@ GEM
   remote: http://rubygems.org/
   specs:
     RedCloth (4.2.9)
-    abstract (1.0.0)
-    actionmailer (3.0.11)
-      actionpack (= 3.0.11)
-      mail (~> 2.2.19)
-    actionpack (3.0.11)
-      activemodel (= 3.0.11)
-      activesupport (= 3.0.11)
-      builder (~> 2.1.2)
-      erubis (~> 2.6.6)
-      i18n (~> 0.5.0)
-      rack (~> 1.2.1)
-      rack-mount (~> 0.6.14)
-      rack-test (~> 0.5.7)
-      tzinfo (~> 0.3.23)
-    activemodel (3.0.11)
-      activesupport (= 3.0.11)
-      builder (~> 2.1.2)
-      i18n (~> 0.5.0)
-    activerecord (3.0.11)
-      activemodel (= 3.0.11)
-      activesupport (= 3.0.11)
-      arel (~> 2.0.10)
-      tzinfo (~> 0.3.23)
-    activeresource (3.0.11)
-      activemodel (= 3.0.11)
-      activesupport (= 3.0.11)
-    activesupport (3.0.11)
-    arel (2.0.10)
-    builder (2.1.2)
+    actionmailer (3.2.3)
+      actionpack (= 3.2.3)
+      mail (~> 2.4.4)
+    actionpack (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.1)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.2)
+    activemodel (3.2.3)
+      activesupport (= 3.2.3)
+      builder (~> 3.0.0)
+    activerecord (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.3)
+      activemodel (= 3.2.3)
+      activesupport (= 3.2.3)
+    activesupport (3.2.3)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    addressable (2.2.8)
+    arel (3.0.2)
+    builder (3.0.0)
     diff-lcs (1.1.3)
-    erubis (2.6.6)
-      abstract (>= 1.0.0)
-    i18n (0.5.0)
-    json (1.6.5)
-    mail (2.2.19)
-      activesupport (>= 2.3.6)
+    erubis (2.7.0)
+    hike (1.2.1)
+    i18n (0.6.0)
+    journey (1.0.3)
+    json (1.7.3)
+    mail (2.4.4)
       i18n (>= 0.4.0)
       mime-types (~> 1.16)
       treetop (~> 1.4.8)
-    mime-types (1.17.2)
+    mime-types (1.18)
+    multi_json (1.2.0)
     polyglot (0.3.3)
-    rack (1.2.5)
-    rack-mount (0.6.14)
-      rack (>= 1.0.0)
-    rack-test (0.5.7)
+    promise (0.3.0)
+    rack (1.4.1)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
       rack (>= 1.0)
-    rails (3.0.11)
-      actionmailer (= 3.0.11)
-      actionpack (= 3.0.11)
-      activerecord (= 3.0.11)
-      activeresource (= 3.0.11)
-      activesupport (= 3.0.11)
+    rails (3.2.3)
+      actionmailer (= 3.2.3)
+      actionpack (= 3.2.3)
+      activerecord (= 3.2.3)
+      activeresource (= 3.2.3)
+      activesupport (= 3.2.3)
       bundler (~> 1.0)
-      railties (= 3.0.11)
-    railties (3.0.11)
-      actionpack (= 3.0.11)
-      activesupport (= 3.0.11)
+      railties (= 3.2.3)
+    railties (3.2.3)
+      actionpack (= 3.2.3)
+      activesupport (= 3.2.3)
+      rack-ssl (~> 1.3.2)
       rake (>= 0.8.7)
       rdoc (~> 3.4)
-      thor (~> 0.14.4)
+      thor (~> 0.14.6)
     rake (0.9.2.2)
     rdoc (3.12)
       json (~> 1.4)
     redcarpet (2.1.1)
-    rspec (2.8.0)
-      rspec-core (~> 2.8.0)
-      rspec-expectations (~> 2.8.0)
-      rspec-mocks (~> 2.8.0)
-    rspec-core (2.8.0)
-    rspec-expectations (2.8.0)
-      diff-lcs (~> 1.1.2)
-    rspec-mocks (2.8.0)
-    rspec-rails (2.8.1)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.0)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    rspec-rails (2.10.1)
       actionpack (>= 3.0)
       activesupport (>= 3.0)
       railties (>= 3.0)
-      rspec (~> 2.8.0)
-    sqlite3 (1.3.5)
+      rspec (~> 2.10.0)
+    simple_oauth (0.1.8)
+    sprockets (2.1.3)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.6)
     thor (0.14.6)
+    tilt (1.3.3)
     treetop (1.4.10)
       polyglot
       polyglot (>= 0.3.1)
-    tzinfo (0.3.31)
+    tzinfo (0.3.33)
+    weary (1.0.1)
+      addressable (~> 2.2.7)
+      multi_json (~> 1.2.0)
+      promise (~> 0.3.0)
+      rack (~> 1.4.0)
+      simple_oauth (~> 0.1.5)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   RedCloth
-  rails (= 3.0.11)
+  rails (>= 3.0.11)
   rake
   redcarpet
   rspec-rails
   sqlite3
+  weary (>= 1.0.1)

data/README.rdoc

@@ -1,3 +1,376 @@
-= Rails API documentation generator
+= API Documentation Tool {<img src="https://secure.travis-ci.org/Pajk/rails-restapi.png?branch=master" alt="Build Status" />}[http://travis-ci.org/Pajk/rails-restapi]
+
+== 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.
+
+Warning: The name rails-restapi is not final and will be changed
+in near future.
+
+== 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 +restapi+ gem to your gemfile and run bundle.
+
+    gem 'restapi'
+
+For bleeding edge version use GitHub version
+
+    gem 'restapi', :git => 'git://github.com/Pajk/rails-restapi.git'
+
+=== Config file
+
+Create configuration file in e.g. */config/initializers/restapi.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
+         Restapi::Markup::Markdown.new or Restapi::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.
+
+Example:
+
+    Restapi.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 = Restapi::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 +restapi+ 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.
+[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'
+        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.
+[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.
+
+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"
+   example " 'user': {...} "
+   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 Restapi::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
+Restapi::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 restapi_validators.rb initializer with this content:
+
+    class IntegerValidator < Restapi::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 error
+        "Parameter \#{@param_name} expecting to be \#{@type.name},
+        got: \#{@error_value.class.name}"
+      end
+
+      def description
+        "Parameter has to be #{@type}."
+      end
+    end
+
+Parameters of the build method:
+
+[param_description] Instance of Restapi::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 Restapi::Markup::Markdown.new. You need Redcarpet gem.
+[Textile] Use Restapi::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 restapi: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
+
+If you provide enough info about your API, you can generate simple CLI client. It is rather skeleton but sufficient for simple use. There is rake task for it: <tt>rake restapi:client</tt>. You can run it with two arguments <tt>rake restapi:client[http://api.example.com,.json]</tt>. The first argument is API base URL (default is http://localhost:3000). Value of second argument is appended to every URL (empty by default) which can be used to specify format. This two values can be also set afterwards from your environment as API_URL and URL_APPEND.
+
+This task create *clients* directory with two files. <tt>Base.rb</tt> contains {Weary}[https://github.com/mwunsch/weary] clients which you can use in your own program, for howto look at {Weary}[https://github.com/mwunsch/weary] documentation. <tt>cli.thor</tt> contains {Thor}[https://github.com/wycats/thor] classes for easy interaction from cli.
+
+Example usage:
+
+    thor list             # list of all available resources and methods
+    thor help users:show  # method and its parameters description
+    thor users:show --id=5 --session=abc # get /users/5?session=abc and print response body
+    thor users:create --user=username:foo password:bar
+
+== TODO
+
+* Dynamic CLI client (read info from documentation API)
+* Add documentation json API description to readme
+[Ideas] * PDF documentation generator
+        * Possibility to create requests from web documentation and check responses
 
-{<img src="https://secure.travis-ci.org/Pajk/rails-restapi.png?branch=master" alt="Build Status" />}[http://travis-ci.org/Pajk/rails-restapi]