apipie-rails 0.0.24 → 0.1.0

data/.gitignore

@@ -5,7 +5,7 @@ spec/dummy/db/*.sqlite3
 spec/dummy/log/*.log
 spec/dummy/tmp/
 .idea
-Gemfile.lock
+Gemfile*.lock
 .rvmrc
 
 .DS_Store

data/.travis.yml

@@ -2,3 +2,9 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.0
+gemfile:
+  - Gemfile.rails30
+  - Gemfile.rails32
+  - Gemfile.rails40
+  - Gemfile.rails41

data/CHANGELOG.md

@@ -0,0 +1,97 @@
+===========
+ Changelog
+===========
+
+v0.1.0
+------
+
+* middleware for computing Apipie checksum for [dynamic bindings](https://github.com/Apipie/apipie-bindings) [#215](https://github.com/Apipie/apipie-rails/pull/215) [@mbacovsky][]
+* `api_base_url` inherited properly [#214](https://github.com/Apipie/apipie-rails/pull/214) [@mbacovsky][]
+* ability to hide specific parameters [#208](https://github.com/Apipie/apipie-rails/pull/208) [@nathanhoel][]
+* fix for SafeYAML compatibility [#207](https://github.com/Apipie/apipie-rails/pull/207) [@pivotalshiny][]
+* option to show all examples in the documentation [#203](https://github.com/Apipie/apipie-rails/pull/203) [@pivotalshiny][]
+* support for array of hashes validation [#189](https://github.com/Apipie/apipie-rails/pull/189) [@mtparet][]
+* support for saving the values based on documentation into `@api_params` variable [#188](https://github.com/Apipie/apipie-rails/pull/188) [@mtparet][]
+* support for json generated from rake task `rake apipie:static_json` [#186](https://github.com/Apipie/apipie-rails/pull/186) [@mtparet][]
+* fix `undefined method 'has_key?' for nil:NilClass` when validating Hash against non-hash value [#185](https://github.com/Apipie/apipie-rails/pull/185) [@mtparet][]
+* fix NoMethorError when validating Hash against non-hash value  [#183](https://github.com/Apipie/apipie-rails/pull/183) [@nathanhoel][]
+* support for metadata for params [#181](https://github.com/Apipie/apipie-rails/pull/181) [@tstrachota][]
+* fix camelization of class names [#170](https://github.com/Apipie/apipie-rails/pull/170) [@yonpols][]
+* new array class validator [#169](https://github.com/Apipie/apipie-rails/pull/169) [@mkrajewski][]
+
+v0.0.24
+-------
+
+* fix DOS vulnerability for running in production without use_cache
+* ability to load descriptions from external files
+* improved examples extractor
+* fixed deprecation warnings in Rails 4
+* using StandardError instead of Exception for errors
+
+v0.0.23
+-------
+
+* fix exceptions on unknown validator
+* fix concerns substitution in parameters
+* possibility to authenticate the API doc
+* support for array in api_controllers_matcher
+
+v0.0.22
+-------
+
+* fix "named_resources" option
+* fix generating static files when concerns used
+
+v0.0.21
+-------
+
+* fix RDoc 4.0 compatibility issue
+* ``validate_value`` and ``validate_presence`` options for better
+  validation granularity
+
+v0.0.20
+-------
+
+* namespaced resources - prevent collisions when one resource defined
+  in more modules
+* ``Apipie::DSL::Concern`` for being able to use the DSL in module
+  that is included into controllers
+
+v0.0.19
+-------
+
+* fix examples recording when resource_id is set
+* use safe_yaml for loading examples file when available
+
+v0.0.18
+-------
+
+* ``param_group`` and ``def_param_group`` keywords
+* ``:action_aware`` options for reusing param groups for create/update actions
+
+v0.0.17
+-------
+
+* support for multiple see links at action and ability to provide
+  description of see links
+
+v0.0.16
+-------
+
+* Fix getting started being rendered even when documentation was available
+
+v0.0.15
+-------
+
+* Fix case when there is no documentation yet: with link to how to
+  start
+* Fix handling bad requests when cache is on
+* Fix params extractor in case there is already some documentation
+
+[@mbacovsky]: https://github.com/mbacovsky
+[@tstrachota]: https://github.com/tstrachota
+[@nathanhoel]: https://github.com/nathanhoel
+[@pivotalshiny]: https://github.com/pivotalshiny
+[@mtparet]: https://github.com/mtparet
+[@yonpols]: https://github.com/yonpols
+[@mkrajewski]: https://github.com/mkrajewski

data/Gemfile

@@ -1,3 +1,3 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gemspec

data/Gemfile.rails30

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rails', '~> 3.0.0'

data/Gemfile.rails32

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rails', '~> 3.2.0'

data/Gemfile.rails40

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rails', '~> 4.0.0'

data/Gemfile.rails41

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rails', '~> 4.1.0.beta'

data/README.rst

@@ -2,11 +2,13 @@
  API Documentation Tool
 ========================
 
-.. image:: https://travis-ci.org/Pajk/apipie-rails.png?branch=master
-    :target: https://travis-ci.org/Pajk/apipie-rails
+.. image:: https://travis-ci.org/Apipie/apipie-rails.png?branch=master
+    :target: https://travis-ci.org/Apipie/apipie-rails
+.. image:: https://codeclimate.com/github/Apipie/apipie-rails.png
+    :target: https://codeclimate.com/github/Apipie/apipie-rails
 
 Apipie-rails is a DSL and Rails engine for documenting you RESTful
-API. Instead of traditional use of ``#comments``, Apipie let's you
+API. Instead of traditional use of ``#comments``, Apipie lets you
 describe the code by code. This brings advantages like:
 
 * no need to learn yet another syntax, you already know Ruby, right?
@@ -32,7 +34,7 @@ The easiest way to get Apipie up and running with your app is:
    $ rails g apipie:install
 
 Now you can start documenting your resources and actions (see
-`DSL Reference`_ for more info:
+`DSL Reference`_ for more info):
 
 .. code:: ruby
 
@@ -65,7 +67,7 @@ Authors
 Contributors
 ------------
 
-See `Contributors page  <https://github.com/Pajk/apipie-rails/graphs/contributors>`_. Special thanks to all of them!
+See `Contributors page  <https://github.com/Apipie/apipie-rails/graphs/contributors>`_. Special thanks to all of them!
 
 License
 -------
@@ -125,6 +127,9 @@ error
 app_info
   In case of versioning, this sets app info description on per_version basis.
 
+meta
+  Hash or array with custom metadata.
+
 Example:
 ~~~~~~~~
 
@@ -140,7 +145,8 @@ Example:
      end
      api_version "development"
      error 404, "Missing"
-     error 500, "Server crashed for some <%= reason %>"
+     error 500, "Server crashed for some <%= reason %>", :meta => {:anything => "you can think of"}
+     meta :author => {:name => 'John', :surname => 'Doe'}
      description <<-EOS
        == Long description
         Example resource for rest api documentation
@@ -206,6 +212,9 @@ see
   Provide reference to another method, this has to be string with
   controller_name#method_name.
 
+meta
+  Hash or array with custom metadata.
+
 Example:
 ~~~~~~~~
 
@@ -213,7 +222,7 @@ Example:
 
    api :GET, "/users/:id", "Show user profile"
    error :code => 401, :desc => "Unauthorized"
-   error :code => 404, :desc => "Not Found"
+   error :code => 404, :desc => "Not Found", :meta => {:anything => "you can think of"}
    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"
@@ -221,8 +230,10 @@ Example:
    param :proc_param, lambda { |val|
      val == "param value" ? true : "The only good value is 'param value'."
    }, :desc => "proc validator"
+   param :param_with_metadata, String, :desc => "", :meta => [:your, :custom, :metadata]
    description "method description"
    formats ['json', 'jsonp', 'xml']
+   meta :message => "Some very important info"
    example " 'user': {...} "
    see "users#showme", "link description"
    see :link => "users#update", :desc => "another link description"
@@ -252,6 +263,15 @@ required
 allow_nil
   Set true is ``nil`` can be passed for this param.
 
+as
+  Use by the processing functionality to change the name of a key params.
+
+meta
+  Hash or array with custom metadata.
+
+show
+  Parameter is hidden from documentation when set to false (true by default)
+
 Example:
 ~~~~~~~~
 
@@ -261,6 +281,7 @@ Example:
      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"
+     param :admin_override, String, :desc => "Not shown in documentation", :show => false
    end
    def create
      #...
@@ -485,6 +506,10 @@ validate_value
 validate_presence
   Check the params presence against the documentation.
 
+process_params
+  Process and extract parameter defined from the params of the request
+  to the api_params variable
+
 app_info
   Application long description.
 
@@ -498,7 +523,7 @@ 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
+  In order to use Markdown you need Maruku 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.
@@ -521,6 +546,9 @@ authenticate
   Pass a proc in order to authenticate user. Pass nil for
   no authentication (by default).
 
+show_all_examples
+  Set this to true to set show_in_doc=1 in all recorded examples
+
 Example:
 
 .. code:: ruby
@@ -532,7 +560,7 @@ Example:
      config.api_base_url = "/api"
      config.validate = false
      config.markup = Apipie::Markup::Markdown.new
-     config.reload_controllers = true
+     config.reload_controllers = Rails.env.development?
      config.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
      config.app_info = "
        This is where you can inform user about your application and API
@@ -541,10 +569,43 @@ Example:
      config.authenticate = Proc.new do
         authenticate_or_request_with_http_basic do |username, password|
           username == "test" && password == "supersecretpassword"
-       end 
+       end
      end
    end
 
+checksum_path
+  Used in ChecksumInHeaders middleware (see `JSON checksums`_ for more info). It contains path prefix(es) where the header with checksum is added. If set to nil, checksum is added in headers in every response. e.g. ``%w[/api /apipie]``
+
+update_checksum
+  If set to true, the checksum is recalculated with every documentation_reload call
+
+============
+ Processing
+============
+
+The goal is to extract and pre process parameters of the request.
+
+For example Rails, by default, transforms empty array to nil value,
+you want perhaps to transform it again to an empty array. Or you
+want to support an enumeration type (comma separated values) and
+you want automatically transform this string to an array.
+
+To use it, set processing_value configuration variable to true.
+In your action, use api_params variable instead of params.
+
+Also by using `as` you can separate your API parameters
+names from the names you are using inside your code.
+
+To implement it, you just have to write a process_value
+function in your validator:
+
+For an enumeration type:
+
+.. code:: ruby
+
+   def process_value(value)
+    value ? value.split(',') : []
+   end
 
 ============
  Validators
@@ -637,6 +698,20 @@ override parameters described on resource level.
      #...
    end
 
+NestedValidator
+-------------
+
+You can describe nested parameters in depth if you provide a block with
+description of nested values.
+
+.. code:: ruby
+
+   param :comments, Array, :desc => "User comments" do
+     param :name, String, :desc => "Name of the comment", :required => true
+     param :comment, String, :desc => "Full comment", :required => true
+   end
+
+
 
 Adding custom validator
 -----------------------
@@ -797,13 +872,52 @@ This will copy the Apipie views to ``app/views/apipie/apipies`` and
 To generate a static version of documentation (perhaps to put it on
 project site or something) run ``rake apipie:static`` task. It will
 create set of html files (multi-pages, single-page, plain) in your doc
-directory. By default the documentation for default API version is
+directory. If you prefer a json version run ``rake apipie:static_json``.
+By default the documentation for default API version is
 used, you can specify the version with ``rake apipie:static[2.0]``
 
 When you want to avoid any unnecessary computation in production mode,
 you can generate a cache with ``rake apipie:cache`` and configure the
 app to use it in production with ``config.use_cache = Rails.env.production?``
 
+===================
+ JSON checksums
+===================
+
+If the API client needs to be sure that the JSON didn't changed, add
+the ``ApipieChecksumInHeaders`` middleware in your rails app.
+It can add checksum of entiere JSON document in the response headers.
+
+.. code::
+
+  "Apipie-Checksum"=>"fb81460e7f4e78d059f826624bdf9504"
+
+`Apipie bindings <https://github.com/Apipie/apipie-bindings>`_ uses this feature to refresh its JSON cache.
+
+To set it up add the following to your ``application.rb``
+
+.. code::
+
+   require 'apipie/middleware/checksum_in_headers'
+   # Add JSON checksum in headers for smarter caching
+   config.middleware.use "Apipie::Middleware::ChecksumInHeaders"
+
+And in your apipie initializer allow checksum calculation
+
+.. code::
+
+   Apipie.configuration.update_checksum = true
+
+and make sure your documentation is loaded.
+
+.. code::
+
+   Apipie.reload_documentation
+
+By default the header is added to responses for ``config.doc_base_url`` and ``/api``.
+It can be changed in configuration (see `Configuration Reference`_ for details).
+
+
 ===================
  Tests Integration
 ===================
@@ -929,6 +1043,7 @@ provided it uses Apipie as a backend.
 
 And if you write one on your own, don't hesitate to share it with us!
 
+
 ====================
  Disqus Integration
 ====================

data/apipie-rails.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |s|
   s.add_dependency "rails", ">= 3.0.10"
   s.add_development_dependency "rspec-rails"
   s.add_development_dependency "sqlite3"
-  s.add_development_dependency "minitest", '~> 4.0'
+  s.add_development_dependency "minitest"
   s.add_development_dependency "maruku"
   s.add_development_dependency "RedCloth"
   s.add_development_dependency "rake"

data/app/controllers/apipie/apipies_controller.rb

@@ -62,6 +62,9 @@ module Apipie
       end
     end
 
+    def apipie_checksum
+    end
+
     private
 
     def get_format

data/app/helpers/apipie_helper.rb

@@ -0,0 +1,9 @@
+module ApipieHelper
+
+  def heading(title, level=1)
+    content_tag("h#{level}") do
+      title
+    end
+  end
+
+end