Skip to content
Browse files

version bump

  • Loading branch information...
1 parent 0b84bb9 commit 58cc90bfd1a6e9645515c0979c85216e83be8825 @Pajk Pajk committed
Showing with 29 additions and 25 deletions.
  1. +28 −24 README.rdoc
  2. +1 −1 lib/restapi/version.rb
View
52 README.rdoc
@@ -4,7 +4,7 @@
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
+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.
@@ -15,10 +15,10 @@ be used for {RESTful}[http://cs.wikipedia.org/wiki/Representational_State_Transf
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
+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
+Warning: The name rails-restapi is not final and will be changed
in near future.
== Why?
@@ -34,7 +34,7 @@ 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
+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.
@@ -49,7 +49,7 @@ https://img.skitch.com/20120428-bni2cmq5cyhjuw1jkd78e3qjxn.png
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'
@@ -67,6 +67,8 @@ of full descriptions.
[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.
@@ -84,6 +86,8 @@ Example:
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.
@@ -98,7 +102,7 @@ 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.
+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.
@@ -137,7 +141,7 @@ Example:
end
#...
end
-
+
=== Method Description
@@ -148,7 +152,7 @@ Then describe methods available to your API.
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.
+ 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.
@@ -157,7 +161,7 @@ Then describe methods available to your API.
[example] Provide example of server response, whole communication or response type.
It will be formatted as code.
-Example:
+Example:
api :GET, "/users/:id", "Show user profile"
error :code => 401, :desc => "Unauthorized"
@@ -166,7 +170,7 @@ Example:
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|
+ param :proc_param, lambda { |val|
val == "param value" ? true : "The only good value is 'param value'."
}, :desc => "proc validator"
description "method description"
@@ -174,7 +178,7 @@ Example:
def show
#...
end
-
+
== Parameter Description
Use +param+ to describe every possible parameter. You can use Hash validator
@@ -186,7 +190,7 @@ in cooperation with block given to param method to describe nested parameters.
[desc] Parameter description.
[required] Set this true/false to make it required/optional.
Default is optional
-
+
Example:
param :user, Hash, :desc => "User info" do
@@ -203,16 +207,16 @@ Example:
Every parameter needs to have associated validator. For now there are some
basic validators. You can always provide your own to reach complex
-results.
+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
+of parameter value expectations. Validations can be turned off
in configuration file.
=== TypeValidator
-Check the parameter type. Only String, Hash and Array are supported
+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.
@@ -222,7 +226,7 @@ your own validator.
=== RegexpValidator
Check parameter value against given regular expression.
-
+
param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
=== ArrayValidator
@@ -240,7 +244,7 @@ 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|
+ param :proc_param, lambda { |val|
val == "param value" ? true : "The only good value is 'param value'."
}, :desc => "proc validator"
@@ -257,7 +261,7 @@ description of nested values.
=== NilValidator
-In fact there is any NilValidator but setting it to nil can be used to
+In fact there is any NilValidator but setting it to nil can be used to
override parameters described on resource level.
Example:
@@ -271,8 +275,8 @@ Example:
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
+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
@@ -284,7 +288,7 @@ 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
@@ -301,12 +305,12 @@ So we create restapi_validators.rb initializer with this content:
def self.build(param_description, argument, options, block)
if argument == Integer || argument == Fixnum
- self.new(param_description, argument)
+ self.new(param_description, argument)
end
end
def error
- "Parameter \#{@param_name} expecting to be \#{@type.name},
+ "Parameter \#{@param_name} expecting to be \#{@type.name},
got: \#{@error_value.class.name}"
end
@@ -362,7 +366,7 @@ Example usage:
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)
View
2 lib/restapi/version.rb
@@ -1,3 +1,3 @@
module Restapi
- VERSION = '0.0.3'
+ VERSION = '0.0.4'
end

0 comments on commit 58cc90b

Please sign in to comment.
Something went wrong with that request. Please try again.