Awesome
Apipie Usage Example Application
This is a sample Rails application demonstrating the features of the Apipie gem.
For more information see the documentation for the Apipie gem.
Getting started
The idea behind this sample app called "TwitterScheduler" is a service that allows you to schedule tweets for users in future. It contains two resources with CRUD operations: users and tweets (that are nested inside the users).
To run this demo, you need to run Ruby 1.9.2 or higher (although the Apipie gem is compatible with 1.8.7).
To get the app up and running run these commands:
bundle install
rake db:setup
rails server
To test that it works we can use curl
to see it working:
curl -H "Content-Type: application/json" -X POST\
-d '{"user":{"name":"admin"}}'\
http://localhost:3000/api/v1/users
curl -H "Content-Type: application/json" -X POST\
-d '{"tweet":{"text":"Hurray, I'\''ve survived",
"scheduled_at":"2012-12-22T01:00"}}'\
http://localhost:3000/api/v1/users/1/tweets
Api Doc In 1 Minute
Setting up the Apipie to be used in our app is simple. We
add the dependency into our Gemfile
and run bundle install
again:
gem 'apipie-rails'
Then set up the basic configuration:
rails g apipie:install --api_path ""
Although we have no documentation yet, routes.rb
and our tests
already contain very interesting information. All we need is to put it
into one place. And Apipie provides a way how to do it:
APIPIE_RECORD=params rake test:functionals
APIPIE_RECORD=examples rake test:functionals
CONGRATULATION!!! You've just created the first cut documentation of your API.
When we open the TweetsController
we can see, that out of a sudden
there is a description of every action. And more then that: the tool
also tried to recognize the type of params if possible (such as the
sent
param is :bool
).
To see the output, just open http://localhost:3000/apipie
.
You might notice that besides the params descriptions there are also
examples available in the documentation, although they are not in the
source code. Apipie uses separate file doc/apipie_examples.yml
.
That makes the code more readable (the examples can really be
disturbing) and also makes it easier to regenerate the examples again
and again.
Time To Share
You might decide to make your documentation available without need to run the service itself. All you need is to run:
rake apipie:static
You can find various versions of the static HTML in doc/apidoc*
files (structured, one-page, plain html).
Versioning
You can specify the resource and/or an action to one or more versions. After that, you can see the documentation for all the versions. You can also generate static files for a given version by running (in this example version 2):
rake apipie:static[2]
DRY
The params can be grouped together and reused for more actions:
# v1/users_controller.rb
def_param_group :address do
param :street, String, "Street name"
param :number, Integer
param :zip, String
end
def_param_group :user do
param :user, Hash, :required => true, :action_aware => true 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
Conclusion
We've just gone through the basic scenarios that are covered by the Apipie gem. I hope you've liked it. For more information see the documentation for the gem. There are other features you might be interested in, such as:
- API for your doc
- different markup languages support
- cache in production
- and others
The tool will be just as good as the users decide it to be. If you find a bug or you have a suggestion for improvement, please file an issue in the Github tracker.