Project

api_tommy

0.0
No commit activity in last 3 years
No release in over 3 years
This generator takes one or several classes with comments formatted in TomDoc and spits out a single Markdown file
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

~> 0.14
~> 0.10
~> 10.4
~> 0.8

Runtime

~> 2.5
~> 4.2
~> 0.4
 Project Readme

ApiTommy

Build Status

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

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