Apipie-rails is a DSL and Rails engine for documenting you RESTful
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?
- possibility reuse the doc for other purposes (such as validation)
- easier to extend and maintain (no string parsing involved)
- possibility to use other sources for documentation purposes (such as routes etc.)
The documentation is available right in your app (by default under
/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 form of JSON.
The easiest way to get Apipie up and running with your app is:
$ 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):
api :GET, '/users/:id'
param :id, :number
def show
# ...
end
Run your application and see the result at
http://localhost:3000/apipie
. For it's further processing, you can
use http://localhost:3000/apipie.json
.
For more comprehensive getting started guide, see this demo, that includes features such as generating documenation from tests, recording examples etc.
See Contributors page. Special thanks to all of them!
Apipie-rails is released under the MIT License
Table Of Contents
You can describe a resource on 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 will the resource 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 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 what 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 per_version basis.
- meta
- Hash or array with custom metadata.
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
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.
- 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 what calling this method. HTTP response code and description can be provided.
- description
- Full method description which will be converted to HTML by chosen 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.
- meta
- Hash or array with custom metadata.
api :GET, "/users/:id", "Show user profile"
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
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
- 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)
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
end
def create
#...
end
Often, params occur together in more actions. Typically, most of the
params for create
and update
actions are common for both of
them.
This 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.
# 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
In CRUD operations, this pattern occurs quite often: params that need to be set are:
- for create action:
required => true
andallow_nil => false
- for update action:
required => false
andallow_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)
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 being inherited from ancestors (in terms of nested params).
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
how to substitute parts of the documentation in the module with controller
specific values. The 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 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
forApi::UsersController
- :resource_id
- Apipie identifier of the resource, e.g.
users
forApi::UsersController
or set byresource_id
# users_module.rb
module UsersModule
extend Apipie::DSL::Concern
api :GET, '/:controller_path', 'List :resource_id'
def index
# ...
end
api :GET, '/:resource_id/:id', '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
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.
- default_version
- Default API version to be used (1.0 by default)
- validate
- Parameters validation is turned off when set to false.
- validate_value
- Check the value of params against specified validators (true by default)
- 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.
- 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. Can be an array if multiple paths are needed
- api_routes
- Set if your application uses custom API router, different from Rails default
- 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 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.
- 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.
- ignored
- An array of controller names (strings) (might include actions as well)
to be ignored when generationg the documentation
e.g.
%w[Api::CommentsController Api::PostsController#post]
- namespaced_resources
- Use controller paths instead of controller names as resource id. This prevents same named controllers overwriting each other.
- 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
- link_extension
- The extension to use for API pages ('.html' by default). Link extensions in static API docs cannot be changed from '.html'.
- languages
- List of languages API documentation should be translated into. Empty list by default.
- default_locale
- Locale used for generating documentation when no specific locale is set. Set to 'en' by default.
- locale
- Pass locale setter/getter
config.locale = lambda { |loc| loc ? FastGettext.set_locale(loc) : FastGettext.locale }
- translate
- Pass proc to translate strings using localization library your project uses. For example see Localization
Example:
Apipie.configure do |config|
config.app_name = "Test app"
config.copyright = "© 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 = Rails.env.development?
config.api_controllers_matcher = File.join(Rails.root, "app", "controllers", "**","*.rb")
config.api_routes = Rails.application.routes
config.app_info = "
This is where you can inform user about your application and API
in general.
", '1.0'
config.authenticate = Proc.new do
authenticate_or_request_with_http_basic do |username, password|
username == "test" && password == "supersecretpassword"
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
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:
def process_value(value)
value ? value.split(',') : []
end
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.
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"
Check parameter value against given regular expression.
param :regexp_param, /^[0-9]* years/, :desc => "regexp param"
Check if parameter value is included given array.
param :array_param, [100, "one", "two", 1, 2], :desc => "array validator"
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"
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
In fact there is any NilValidator but setting it to nil can be used to override parameters described on resource level.
param :user, nil
def destroy
#...
end
You can describe nested parameters in depth if you provide a block with description of nested values.
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
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
{:desc => "Company ID"}
- block
- Block converted into Proc, use it as you desire. In this example nil.
Every resource/method can belong to one or more versions. The version is specified with the api_version DSL keyword. When not specified, the resource belong to config.default_version ("1.0" by default)
resource_description do
api_versions "1", "2"
end
api :GET, "/api/users/"
api_version "1"
def index
# ...
end
In the example above we say the whole controller/resource is defined for versions "1" and "2", but we override this with explicitly saying index belongs only to version "1". Also inheritance works (therefore we can specify the api_version for the parent controller and all children will know about that).
From the Apipie API perspective, the resources belong to version. With versioning, there are paths like this provided by apipie:
/apipie/1/users/index /apipie/2/users/index
When not specifying the version explicitly in the path (or in dsl), default version (Apipie.configuration.default_version) is used instead ("1.0" by default). Therefore, the application that doesn't need versioning should work as before.
The static page generator takes version parameter (or uses default).
You can specify the versions for the examples, with versions keyword. It specifies the versions the example is used for. When not specified, it's shown in all versions with given method.
When referencing or quering the resource/method descripion, this format should be used: "verson#resource#method". When not specified, the default version is used instead.
The default markup language is RDoc. It can be changed in
config file (config.markup=
) to one of these:
- Markdown
- Use Apipie::Markup::Markdown.new. You need Maruku gem.
- Textile
- Use Apipie::Markup::Textile.new. You need RedCloth gem.
Or provide you own object with to_html(text)
method.
For inspiration this is how Textile markup usage looks like:
class Textile
def initialize
require 'RedCloth'
end
def to_html(text)
RedCloth.new(text).to_html
end
end
Apipie has support for localized API documentation in both formats (JSON and HTML).
Apipie uses the library I18n for localization of itself.
Check config/locales
directory for available translation.
Major part of strings in the documentation comes from the API. As prefferences about localization libraries differs among project, Apipie needs to know how to set locale for your project and how to translate a string using library your project use. That can be done using lambdas in configuration.
Sample configuration when your project use FastGettext
Apipie.configure do |config|
...
config.languages = ['en', 'cs']
config.default_locale = 'en'
config.locale = lambda { |loc| loc ? FastGettext.set_locale(loc) : FastGettext.locale }
config.translate = lambda do |str, loc|
old_loc = FastGettext.locale
FastGettext.set_locale(loc)
trans = _(str)
FastGettext.set_locale(old_loc)
trans
end
end
And the strings in API documentation needs to be marked with the N_()
function
api :GET, "/users/:id", N_("Show user profile")
param :session, String, :desc => N_("user is logged in"), :required => true
When your project use I18n, localization related configuration could look like as follows
Apipie.configure do |config|
...
config.languages = ['en', 'cs']
config.default_locale = 'en'
config.locale = lambda { |loc| loc ? I18n.locale = loc : I18n.locale }
config.translate = lambda do |str, loc|
old_loc = I18n.locale
I18n.locale = loc
trans = I18n.t(str)
I18n.locale = old_loc
trans
end
end
And the strings in API documentation needs to be in the form of translation keys
api :GET, "/users/:id", "show_user_profile"
param :session, String, :desc => "user_is_logged_in", :required => true
The localized versions of the documentation are distinguished by languge in the filename.
E.g. doc/apidoc/apidoc.cs.html
is static documentation in the Czech language.
If the language is missing, e.g. doc/apidoc/apidoc.html
,
the documentation is localized with the default_locale
.
The dynamic documentation follows the same schema. The http://localhost:3000/apidoc/v1.cs.html
is documentation for version '1' of the API in the Czech language. For JSON description of the API applies the same: http://localhost:3000/apidoc/v1.cs.json
To modify the views of your documentation, run rails g apipie:views
.
This will copy the Apipie views to app/views/apipie/apipies
and
app/views/layouts/apipie
.
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. 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?
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.
"Apipie-Checksum"=>"fb81460e7f4e78d059f826624bdf9504"
Apipie bindings uses this feature to refresh its JSON cache.
To set it up add the following to your application.rb
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
Apipie.configuration.update_checksum = true
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).
The checksum calculation is lazy, done with first request. If you run with use_cache = true
,
do not forget to run the rake task apipie:cache
.
Apipie integrates with automated testing in two ways. Documentation bootstrapping and examples recording.
Let's say you have an application without REST API documentation. However you have a set of tests that are run against this API. A lot of information is already included in this tests, it just needs to be extracted somehow. Luckily, Apipie provides such a feature.
When running the tests, set the APIPIE_RECORD=params
environment
variable or call Apipie.record('params')
from specs starter. You can either use it with functional tests
APIPIE_RECORD=params rake test:functionals
or you can run your server with this param, in case you run the tests against running server
APIPIE_RECORD=params rails server
When the process quits, the data from requests/responses are used to determine the documentation. It's quite raw, but it makes the initial phase much easier.
You can also use the tests to generate up-to-date examples for your
code. Similarly to the bootstrapping, you can use it with functional
tests or a running server, setting APIPIE_RECORD=examples
or by calling Apipie.record('examples')
in your specs starter.
APIPIE_RECORD=examples rake test:functionals APIPIE_RECORD=examples rails server
The data is written into doc/apipie_examples.yml
. By default,
only the first example is shown for each action. You can customize
this by setting show_in_doc
attribute at each example.
--- !omap - announcements#index: - !omap - verb: :GET - path: /api/blabla/1 - versions: - '1.0' - query: - request_data: - response_data: ... - code: 200 - show_in_doc: 1 # If 1, show. If 0, do not show. - recorded: true
In RSpec you can add metadata to examples. We can use that feature to mark selected examples โ the ones that perform the requests that we want to show as examples in the documentation.
For example, we can add show_in_doc
to examples, like this:
describe "This is the correct path" do
it "some test", :show_in_doc do
....
end
end
context "These are edge cases" do
it "Can't authenticate" do
....
end
it "record not found" do
....
end
end
And then configure RSpec in this way:
RSpec.configure do |config|
config.treat_symbols_as_metadata_keys_with_true_values = true
config.filter_run :show_in_doc => true if ENV['APIPIE_RECORD']
end
This way, when running in recording mode, only the tests that has been marked with the
:show_in_doc
metadata will be ran, and hence only those will be used as examples.
In earlier versions (<= 0.0.13), there was a simple client generator as a part of Apipie gem. As more features and users came to Apipie, more and more there was a need for changes on per project basis. It's hard (or even impossible) to provide a generic solution for the client code. We also don't want to tell you what's the rigth way to do it (what gems to use, how the API should look like etc.).
Therefore you can't generate a client code directly by a rake task in further versions.
There is, however, even better and more flexible way to reuse your API documentation for this purpose: using the API the Apipie provides in the generator code. You can inspire by Foreman API bindings that use exactly this approach. You also don't need to run the service, provided it uses Apipie as a backend.
And if you write one on your own, don't hesitate to share it with us!
You can get a Disqus discussion for the right into your documentation. Just set the credentials in Apipie configuration:
config.disqus_shortname = "MyProjectDoc"
- Getting started tutorial - including examples of using the tests integration and versioning.
- Real-world application usage
- Read-world application usage with versioning
- Using Apipie API to generate bindings