ApiTommy

ApiTommy is an opinionated little tool used to generate a wiki page documenting your APIs based on Rails/Rails-api.

Basically, you document your classes using a standard. There is no modification in your code. You then run this tool and it will automatically generate and update your github wiki.

This tool depends on rdoc 4.2.x

Compatibility

rails 4.2.x
rdoc 4.2.x

This gem is built against:

ruby 1.9.3
ruby 2.0.0
ruby 2.1.3
ruby 2.2.0

Other versions may or may not work.

Installation

Add this line to your application's Gemfile:

gem 'api_tommy'

And then execute:

$ bundle

Or install it yourself as:

$ gem install api_tommy

Usage

Here is the requirements in order to have an happy tommy (pun intended):

The best place to document your API is your controllers.
Each class/method is documented using TomDoc.
For the class comments, here is the usage of each TomDoc section:
- Description: Will describe your API and the returned objects
- Returns: Not used.
- Arguments: Will describe each field of your objects
- Examples: Will provide examples of your object
- Raises: Not used.
For the method comments, here is the usage of each TomDoc section:
- Description: Will describe your method with its constraints. The first sentence will be used as a title for the wiki.
- Returns: Will describe the structure returned. Is it an array? A single object?
- Arguments: Will describe each parameter accepted by the method.
- Examples: Examples of how do you call your API method.
- Raises: Will describe what exceptions can occur. Ideally, it should be http codes(eg 400, 404, ...).
You are using Ruby 1.9.3.
You are using Rails 3.x or 4.
Your project is hosted on github and has a wiki.

Let's see an example. Here a really simple API documented controller:

# This is the cars API. It provides ways to search and get cars.
# Cars are simple json objects with these fields:
#
# brand - the brand of the car
# model - the model of the car
# horsepower - the horse power of the car
# year - the year of the car
#
# Examples
#
# {
#   "car": {
#     "brand": "Mini",
#     "model": "Cooper S",
#     "horsepower": 400,
#     "year": 2050
#   }
# }
class CarsController < ApplicationController

  # Get all cars. This method will return all available cars
  #
  # Examples
  #
  # GET /cars.json
  #
  # Returns all cars as an array under the `cars` field.
  # Raises 500 if an error occurs
  def index
    render :json => Car.all
  end

  # Get a car. This method will return the given car's id.
  #
  # id - the car's id as a string.
  #
  # Examples
  #
  # GET /cars/1237.json
  #
  # Return the given car under the `car`field.
  # Raises 404 if the car can't be found.
  # Raises 500 if an error occurs
  def show
    render :json => Car.find(params[:id])
  end
end

On the root of the project, you can then run the following command:

rdoc --format apitommy app/controllers/cars_controller.rb

This will lead to a page API in your project wiki, containing this markup:

# Cars

This is the cars API. It provides ways to search and get cars. Cars are simple json objects with these fields:

### Fields

| Name | Description
| --- | ---
| brand | the brand of the car
| model | the model of the car
| horsepower | the horse power of the car
| year | the year of the car

### Examples

{
  "car": {
    "brand": "Mini",
    "model": "Cooper S",
    "horsepower": 400,
    "year": 2050
  }
}

## Get all cars

Get all cars. This method will return all available cars

Returns all cars as an array under the `cars` field.

### Examples

GET /cars.json

### Errors

500 if an error occurs

## Get a car

Get a car. This method will return the given car's id.

Return the given car under the `car`field.

### Parameters

| Name | Description
| --- | ---
| id | the car's id as a string.

### Examples

GET /cars/1237.json

### Errors

404 if the car can't be found.

500 if an error occurs

Options

When running rdoc --format apitommy, these options are available:

--filename FILENAME: the name of the wiki page. API by default.
--header HEADER: if you wish to include a header on the wiki page. Optionnal.
--footer FOOTER: if you wish to include a footer on the wiki page. Optionnal.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request