<commit_before>========================
 API Documentation Tool
========================

.. 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 your RESTful
API. Instead of traditional use of ``#comments``, Apipie lets you
describe the code, through the code. This brings advantages like:

* No need to learn yet another syntax, you already know Ruby, right?
* Possibility of reusing the docs for other purposes (such as validation)
* Easier to extend and maintain (no string parsing involved)
* Possibility of reusing other sources for documentation purposes (such as
  routes etc.)

The documentation is available from within your app (by default under the
``/apipie`` path.) In development mode, you can see the changes as you
go. It's markup language agnostic, and even provides an API for reusing
the documentation data in JSON.

Getting started
---------------

The easiest way to get Apipie up and running with your app is:

.. code:: sh

   echo "gem 'apipie-rails'" >> Gemfile
   bundle install
   rails g apipie:install

Now you can start documenting your resources and actions (see
`DSL Reference`_ for more info):

.. code:: ruby

   api :GET, '/users/:id'
   param :id, :number
   def show
     # ...
   end


Run your application and see the result at
``http://localhost:3000/apipie``. For further processing, you can
use ``http://localhost:3000/apipie.json``.

For a more comprehensive getting started guide, see
`this demo <https://github.com/iNecas/apipie-demo>`_, which includes
features such as generating documentation from tests, recording examples etc.

Screenshots
-----------

.. image:: https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-1.png
.. image:: https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-2.png

Authors
-------

`Pajk <https://github.com/Pajk>`_ and `iNecas <https://github.com/iNecas>`_

Contributors
------------

See `Contributors page  <https://github.com/Apipie/apipie-rails/graphs/contributors>`_. Special thanks to all of them!

License
-------

Apipie-rails is released under the `MIT License <http://opensource.org/licenses/MIT>`_

===============
 Documentation
===============

.. contents:: `Table Of Contents`
  :depth: 2

===============
 DSL Reference
===============

Resource Description
--------------------

You can describe a resource on the controller level. The description is introduced by calling
``resource_description do ... end``.

Inheritance is supported, so you can specify common params for group of controllers in their parent
class.

The following keywords are available (all are optional):

resource_id
  How the resource will be referenced in Apipie (paths, ``see`` command etc.); by default `controller_name.downcase` is used.

name
  Human readable name of resource. By default ``class.name.humanize`` is used.

short (also short_description)
  Short description of the resource (it's shown on both the list of resources, and resource details)

desc (also description and full_description)
  Full description of the resource (shown only in resource details)

param
  Common params for all methods defined in controller/child controllers.

api_base_url
  What URL is the resource available under.

api_versions (also api_version)
  What versions does the controller define the resource. (See `Versioning`_ for details.)

formats
  Request / response formats.

error
  Describe every possible error that can happen when calling all
  methods defined in controller. HTTP response code and description can be provided.

app_info
  In case of versioning, this sets app info description on a per_version basis.

meta
  Hash or array with custom metadata.

Example:
~~~~~~~~

.. code:: ruby

   resource_description do
     short 'Site members'
     formats ['json']
     param :id, Fixnum, :desc => "User ID", :required => false
     param :resource_param, Hash, :desc => 'Param description for all methods' do
       param :ausername, String, :desc => "Username for login", :required => true
       param :apassword, String, :desc => "Password for login", :required => true
     end
     api_version "development"
     error 404, "Missing"
     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
        These can now be accessed in <tt>shared/header</tt> with:
          Headline: <%= headline %>
          First name: <%= person.first_name %>

        If you need to find out whether a certain local variable has been
        assigned a value in a particular render call, you need to use the
        following pattern:

        <% if local_assigns.has_key? :headline %>
           Headline: <%= headline %>
        <% end %>

       Testing using <tt>defined? headline</tt> will not work. This is an
       implementation restriction.

       === Template caching

       By default, Rails will compile each template to a method in order
       to render it. When you alter a template, Rails will check the
       file's modification time and recompile it in development mode.
     EOS
   end


Method Description
------------------

Then describe methods available to your API.

api
  Describe how this method is exposed, and provide a short description.
  The first parameter is HTTP method (one of :GET/:POST/:PUT/:DELETE).
  The second parameter is the relative URL path which is mapped to this
  method. The last parameter is the methods short description.
  You can use this +api+ method more than once per method. It could
  be useful when there are more routes mapped to it.

  When providing just one argument (description), or no argument at all,
  the paths will be loaded from the routes.rb file.

api!
  Provide a short description and additional option.
  The last parameter is the methods short description.
  The paths will be loaded from routes.rb file. See
  `Rails Routes Integration`_ for more details.

api_versions (also api_version)
  What version(s) does the action belong to. (See `Versioning`_ for details.)

param
  Look at Parameter description section for details.

formats
  Method level request / response formats.

error
  Describe each possible error that can happen while calling this
  method. HTTP response code and description can be provided.

description
  Full method description, which will be converted into HTML by the
  chosen markup language processor.

example
  Provide an example of the server response; whole communication or response type.
  It will be formatted as code.

see
  Provide reference to another method, this has to be a string with
  controller_name#method_name.

meta
  Hash or array with custom metadata.

show
  Resource is hidden from documentation when set to false (true by default)

Example:
~~~~~~~~

.. code:: ruby

   # The simplest case: just load the paths from routes.rb
   api!
   def index
   end

   # More complex example
   api :GET, "/users/:id", "Show user profile"
   show false
   error :code => 401, :desc => "Unauthorized"
   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"
   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"
   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"
   def show
     #...
   end


Parameter Description
---------------------

Use ``param`` to describe every possible parameter. You can use the Hash validator
in conjunction with a block given to the param method to describe nested parameters.

name
  The first argument is the parameter name as a symbol.

validator
  Second parameter is the parameter validator, choose one from section `Validators`_

desc
  Parameter description.

required
  Set this true/false to make it required/optional. Default is optional

allow_nil
  Setting this to true means that ``nil`` can be passed.

as
  Used 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)

missing_message
  Specify the message to be returned if the parameter is missing as a string or Proc.
  Defaults to ``Missing parameter #{name}`` if not specified.

Example:
~~~~~~~~

.. code:: ruby

   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"
     param :admin_override, String, :desc => "Not shown in documentation", :show => false
     param :ip_address, String, :desc => "IP address", :required => true, :missing_message => lambda { I18n.t("ip_address.required") }
   end
   def create
     #...
   end

DRY with param_group
--------------------

Often, params occur together in more actions. Typically, most of the
params for ``create`` and ``update`` actions are shared between them.

These params can be extracted with ``def_param_group`` and
``param_group`` keywords.

The definition is looked up in the scope of the controller. If the
group is defined in a different controller, it might be referenced by
specifying the second argument.

Example:
~~~~~~~~

.. code:: ruby

   # v1/users_controller.rb
   def_param_group :address do
     param :street, String
     param :number, Integer
     param :zip, String
   end

   def_param_group :user do
     param :user, Hash do
       param :name, String, "Name of the user"
       param_group :address
     end
   end

   api :POST, "/users", "Create an user"
   param_group :user
   def create
     # ...
   end

   api :PUT, "/users/:id", "Update an user"
   param_group :user
   def update
     # ...
   end

   # v2/users_controller.rb
   api :POST, "/users", "Create an user"
   param_group :user, V1::UsersController
   def create
     # ...
   end

Action Aware params
-------------------

In CRUD operations, this pattern occurs quite often - params that need
to be set are:

* for create action: ``required => true`` and ``allow_nil => false``
* for update action: ``required => false`` and ``allow_nil => false``

This makes it hard to share the param definitions across theses
actions. Therefore, you can make the description a bit smarter by
setting ``:action_aware => true``.

You can specify explicitly how the param group should be evaluated
with ``:as`` option (either :create  or :update)

Example
~~~~~~~

.. code:: ruby

   def_param_group :user do
     param :user, Hash, :action_aware => true do
       param :name, String, :required => true
       param :description, :String
     end
   end

   api :POST, "/users", "Create an user"
   param_group :user
   def create
     # ...
   end

   api :PUT, "/users/admin", "Create an admin"
   param_group :user, :as => :create
   def create_admin
     # ...
   end

   api :PUT, "/users/:id", "Update an user"
   param_group :user
   def update
     # ...
   end

In this case, ``user[name]`` will be not be allowed nil for all
actions and required only for ``create`` and ``create_admin``. Params
with ``allow_nil`` set explicitly don't have this value changed.

Action awareness is inherited from ancestors (in terms of
nested params).

Concerns
--------

Sometimes, the actions are not defined in the controller class
directly but included from a module instead. You can load the Apipie
DSL into the module by extending it with ``Apipie::DSL::Concern``.

The module can be used in more controllers. Therefore there is a way to
substitute parts of the documentation in the module with controller
specific values. These substitutions can be stated explicitly with
``apipie_concern_subst(:key => "value")`` (needs to be called before
the module is included to take effect). The substitutions are
performed in the paths and descriptions of APIs and names and descriptions
of params.

There are some default substitutions available:

:controller_path
  value of ``controller.controller_path``, e.g. ``api/users`` for
  ``Api::UsersController``. Only if not using the ``api!`` keyword.

:resource_id
  Apipie identifier of the resource, e.g. ``users`` for
  ``Api::UsersController`` or set by ``resource_id``

Example
~~~~~~~

.. code:: ruby

   # users_module.rb
   module UsersModule
     extend Apipie::DSL::Concern

     api :GET, '/:controller_path', 'List :resource_id'
     def index
       # ...
     end

     api! 'Show a :resource'
     def show
       # ...
     end

     api :POST, '/:resource_id', "Create a :resource"
     param :concern, Hash, :required => true
       param :name, String, 'Name of a :resource'
       param :resource_type, ['standard','vip']
     end
     def create
       # ...
     end

     api :GET, '/:resource_id/:custom_subst'
     def custom
       # ...
     end
   end

   # users_controller.rb
   class UsersController < ApplicationController

     resource_description { resource_id 'customers' }

     apipie_concern_subst(:custom_subst => 'custom', :resource => 'customer')
     include UsersModule

     # the following paths are documented
     # api :GET, '/users'
     # api :GET, '/customers/:id', 'Show a customer'
     # api :POST, '/customers', 'Create a customer'
     #   param :customer, :required => true do
     #     param :name, String, '<NAME>'
     #     param :customer_type, ['standard', 'vip']
     #   end
     # api :GET, '/customers/:custom'
   end



=========================
 Configuration Reference
=========================

Create a configuration file in e.g. ``/config/initializers/apipie.rb``.
You can set the application name, footer text, API and documentation base URL
and turn off validations. You can also choose your favorite markup language
for 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.

default_version
  Default API version to be used (1.0 by default)

validate
  Parameters validation is turned off when set to false. When set to
  ``:explicitly``, you must invoke parameter validation yourself by calling
  controller method ``apipie_validations`` (typically in a before_filter).
  When set to ``:implicitly`` (or just true), your controller's action
  methods are wrapped with generated methods which call ``apipie_validations``,
  and then call the action method. (``:implicitly`` by default)

validate_value
  Check the value of params against specified validators (true by
  default)

validate_presence
  Check the params presence against the documentation.

validate_key
  Check the received params to ensure they are defined in the API. (false by default)<commit_msg>Update README.md [ci skip]<commit_after>========================
 API Documentation Tool
========================

.. 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 your RESTful
API. Instead of traditional use of ``#comments``, Apipie lets you
describe the code, through the code. This brings advantages like:

* No need to learn yet another syntax, you already know Ruby, right?
* Possibility of reusing the docs for other purposes (such as validation)
* Easier to extend and maintain (no string parsing involved)
* Possibility of reusing other sources for documentation purposes (such as
  routes etc.)

The documentation is available from within your app (by default under the
``/apipie`` path.) In development mode, you can see the changes as you
go. It's markup language agnostic, and even provides an API for reusing
the documentation data in JSON.

Getting started
---------------

The easiest way to get Apipie up and running with your app is:

.. code:: sh

   echo "gem 'apipie-rails'" >> Gemfile
   bundle install
   rails g apipie:install

Now you can start documenting your resources and actions (see
`DSL Reference`_ for more info):

.. code:: ruby

   api :GET, '/users/:id'
   param :id, :number
   def show
     # ...
   end


Run your application and see the result at
``http://localhost:3000/apipie``. For further processing, you can
use ``http://localhost:3000/apipie.json``.

For a more comprehensive getting started guide, see
`this demo <https://github.com/iNecas/apipie-demo>`_, which includes
features such as generating documentation from tests, recording examples etc.

Screenshots
-----------

.. image:: https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-1.png
.. image:: https://github.com/Apipie/apipie-rails/blob/master/images/screenshot-2.png

Authors
-------

`Pajk <https://github.com/Pajk>`_ and `iNecas <https://github.com/iNecas>`_

Contributors
------------

See `Contributors page  <https://github.com/Apipie/apipie-rails/graphs/contributors>`_. Special thanks to all of them!

License
-------

Apipie-rails is released under the `MIT License <http://opensource.org/licenses/MIT>`_

===============
 Documentation
===============

.. contents:: `Table Of Contents`
  :depth: 2

===============
 DSL Reference
===============

Resource Description
--------------------

You can describe a resource on the controller level. The description is introduced by calling
``resource_description do ... end``.

Inheritance is supported, so you can specify common params for group of controllers in their parent
class.

The following keywords are available (all are optional):

resource_id
  How the resource will be referenced in Apipie (paths, ``see`` command etc.); by default `controller_name.downcase` is used.

name
  Human readable name of resource. By default ``class.name.humanize`` is used.

short (also short_description)
  Short description of the resource (it's shown on both the list of resources, and resource details)

desc (also description and full_description)
  Full description of the resource (shown only in resource details)

param
  Common params for all methods defined in controller/child controllers.

api_base_url
  What URL is the resource available under.

api_versions (also api_version)
  What versions does the controller define the resource. (See `Versioning`_ for details.)

formats
  Request / response formats.

error
  Describe every possible error that can happen when calling all
  methods defined in controller. HTTP response code and description can be provided.

app_info
  In case of versioning, this sets app info description on a per_version basis.

meta
  Hash or array with custom metadata.

Example:
~~~~~~~~

.. code:: ruby

   resource_description do
     short 'Site members'
     formats ['json']
     param :id, Fixnum, :desc => "User ID", :required => false
     param :resource_param, Hash, :desc => 'Param description for all methods' do
       param :ausername, String, :desc => "Username for login", :required => true
       param :apassword, String, :desc => "Password for login", :required => true
     end
     api_version "development"
     error 404, "Missing"
     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
        These can now be accessed in <tt>shared/header</tt> with:
          Headline: <%= headline %>
          First name: <%= person.first_name %>

        If you need to find out whether a certain local variable has been
        assigned a value in a particular render call, you need to use the
        following pattern:

        <% if local_assigns.has_key? :headline %>
           Headline: <%= headline %>
        <% end %>

       Testing using <tt>defined? headline</tt> will not work. This is an
       implementation restriction.

       === Template caching

       By default, Rails will compile each template to a method in order
       to render it. When you alter a template, Rails will check the
       file's modification time and recompile it in development mode.
     EOS
   end


Method Description
------------------

Then describe methods available to your API.

api
  Describe how this method is exposed, and provide a short description.
  The first parameter is HTTP method (one of :GET/:POST/:PUT/:DELETE).
  The second parameter is the relative URL path which is mapped to this
  method. The last parameter is the methods short description.
  You can use this +api+ method more than once per method. It could
  be useful when there are more routes mapped to it.

  When providing just one argument (description), or no argument at all,
  the paths will be loaded from the routes.rb file.

api!
  Provide a short description and additional option.
  The last parameter is the methods short description.
  The paths will be loaded from routes.rb file. See
  `Rails Routes Integration`_ for more details.

api_versions (also api_version)
  What version(s) does the action belong to. (See `Versioning`_ for details.)

param
  Look at Parameter description section for details.

formats
  Method level request / response formats.

error
  Describe each possible error that can happen while calling this
  method. HTTP response code and description can be provided.

description
  Full method description, which will be converted into HTML by the
  chosen markup language processor.

example
  Provide an example of the server response; whole communication or response type.
  It will be formatted as code.

see
  Provide reference to another method, this has to be a string with
  controller_name#method_name.

meta
  Hash or array with custom metadata.

show
  Resource is hidden from documentation when set to false (true by default)

Example:
~~~~~~~~

.. code:: ruby

   # The simplest case: just load the paths from routes.rb
   api!
   def index
   end

   # More complex example
   api :GET, "/users/:id", "Show user profile"
   show false
   error :code => 401, :desc => "Unauthorized"
   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"
   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"
   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"
   def show
     #...
   end


Parameter Description
---------------------

Use ``param`` to describe every possible parameter. You can use the Hash validator
in conjunction with a block given to the param method to describe nested parameters.

name
  The first argument is the parameter name as a symbol.

validator
  Second parameter is the parameter validator, choose one from section `Validators`_

desc
  Parameter description.

required
  Set this true/false to make it required/optional. Default is optional

allow_nil
  Setting this to true means that ``nil`` can be passed.

as
  Used 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)

missing_message
  Specify the message to be returned if the parameter is missing as a string or Proc.
  Defaults to ``Missing parameter #{name}`` if not specified.

Example:
~~~~~~~~

.. code:: ruby

   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"
     param :admin_override, String, :desc => "Not shown in documentation", :show => false
     param :ip_address, String, :desc => "IP address", :required => true, :missing_message => lambda { I18n.t("ip_address.required") }
   end
   def create
     #...
   end

DRY with param_group
--------------------

Often, params occur together in more actions. Typically, most of the
params for ``create`` and ``update`` actions are shared between them.

These params can be extracted with ``def_param_group`` and
``param_group`` keywords.

The definition is looked up in the scope of the controller. If the
group is defined in a different controller, it might be referenced by
specifying the second argument.

Example:
~~~~~~~~

.. code:: ruby

   # v1/users_controller.rb
   def_param_group :address do
     param :street, String
     param :number, Integer
     param :zip, String
   end

   def_param_group :user do
     param :user, Hash do
       param :name, String, "Name of the user"
       param_group :address
     end
   end

   api :POST, "/users", "Create an user"
   param_group :user
   def create
     # ...
   end

   api :PUT, "/users/:id", "Update an user"
   param_group :user
   def update
     # ...
   end

   # v2/users_controller.rb
   api :POST, "/users", "Create an user"
   param_group :user, V1::UsersController
   def create
     # ...
   end

Action Aware params
-------------------

In CRUD operations, this pattern occurs quite often - params that need
to be set are:

* for create action: ``required => true`` and ``allow_nil => false``
* for update action: ``required => false`` and ``allow_nil => false``

This makes it hard to share the param definitions across theses
actions. Therefore, you can make the description a bit smarter by
setting ``:action_aware => true``.

You can specify explicitly how the param group should be evaluated
with ``:as`` option (either :create  or :update)

Example
~~~~~~~

.. code:: ruby

   def_param_group :user do
     param :user, Hash, :action_aware => true do
       param :name, String, :required => true
       param :description, :String
     end
   end

   api :POST, "/users", "Create an user"
   param_group :user
   def create
     # ...
   end

   api :PUT, "/users/admin", "Create an admin"
   param_group :user, :as => :create
   def create_admin
     # ...
   end

   api :PUT, "/users/:id", "Update an user"
   param_group :user
   def update
     # ...
   end

In this case, ``user[name]`` will be not be allowed nil for all
actions and required only for ``create`` and ``create_admin``. Params
with ``allow_nil`` set explicitly don't have this value changed.

Action awareness is inherited from ancestors (in terms of
nested params).

Concerns
--------

Sometimes, the actions are not defined in the controller class
directly but included from a module instead. You can load the Apipie
DSL into the module by extending it with ``Apipie::DSL::Concern``.

The module can be used in more controllers. Therefore there is a way to
substitute parts of the documentation in the module with controller
specific values. These substitutions can be stated explicitly with
``apipie_concern_subst(:key => "value")`` (needs to be called before
the module is included to take effect). The substitutions are
performed in the paths and descriptions of APIs and names and descriptions
of params.

There are some default substitutions available:

:controller_path
  value of ``controller.controller_path``, e.g. ``api/users`` for
  ``Api::UsersController``. Only if not using the ``api!`` keyword.

:resource_id
  Apipie identifier of the resource, e.g. ``users`` for
  ``Api::UsersController`` or set by ``resource_id``

Example
~~~~~~~

.. code:: ruby

   # users_module.rb
   module UsersModule
     extend Apipie::DSL::Concern

     api :GET, '/:controller_path', 'List :resource_id'
     def index
       # ...
     end

     api! 'Show a :resource'
     def show
       # ...
     end

     api :POST, '/:resource_id', "Create a :resource"
     param :concern, Hash, :required => true
       param :name, String, 'Name of a :resource'
       param :resource_type, ['standard','vip']
     end
     def create
       # ...
     end

     api :GET, '/:resource_id/:custom_subst'
     def custom
       # ...
     end
   end

   # users_controller.rb
   class UsersController < ApplicationController

     resource_description { resource_id 'customers' }

     apipie_concern_subst(:custom_subst => 'custom', :resource => 'customer')
     include UsersModule

     # the following paths are documented
     # api :GET, '/users'
     # api :GET, '/customers/:id', 'Show a customer'
     # api :POST, '/customers', 'Create a customer'
     #   param :customer, :required => true do
     #     param :name, String, 'Name of a customer'
     #     param :customer_type, ['standard', 'vip']
     #   end
     # api :GET, '/customers/:custom'
   end



=========================
 Configuration Reference
=========================

Create a configuration file in e.g. ``/config/initializers/apipie.rb``.
You can set the application name, footer text, API and documentation base URL
and turn off validations. You can also choose your favorite markup language
for 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 for default version of your API. To set it for specific version use ``config.api_base_url[version] = url``.

default_version
  Default API version to be used (1.0 by default)

validate
  Parameters validation is turned off when set to false. When set to
  ``:explicitly``, you must invoke parameter validation yourself by calling
  controller method ``apipie_validations`` (typically in a before_filter).
  When set to ``:implicitly`` (or just true), your controller's action
  methods are wrapped with generated methods which call ``apipie_validations``,
  and then call the action method. (``:implicitly`` by default)

validate_value
  Check the value of params against specified validators (true by
  default)

validate_presence
  Check the params presence against the documentation.

validate_key
  Check the received params to ensure they are defined in the API. (false by default)
{'fraction_non_alphanumeric': 0.11052166224580018, 'fraction_numerical': 0.0023367437160540607, 'mean_word_length': 3.3784045347711875, 'pattern_counts': {'":': 0, '<': 40, '<?xml version=': 0, '>': 144, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2669791', 'n_tokens_mistral': 8917, 'n_tokens_neox': 8583, 'n_words': 3840}