API Buddy

Usage

You have a JSON API build in Rails.

You have mobile developers (iOS, Android etc.) who rely on this API.

You want to give them stubbed endpoints for new features ASAP.

You want to be able to seemlessly implement parts of the stubbed API, without interrupting their workflow.

Once the new features have been implemented, we should be able to use the exact same DSL used for stubbing the endpoints, to generate both documentation and tests.

Project Structure

1) Builder DSL

Take a DSL for defining the characteristics of a JSON API and build data structure to represent the API endpoints and attributes.

# ./api_doc/posts_endpoints.rb

endpoint '/api/posts', method: :post do
  description 'Creates a post in the database'

  json 'post' do
    attribute 'id', :integer
    attribute 'title', :string, example: 'Ruby is Great'
    attribute 'author_id', :integer, example: 2
    attribute 'author_name', :string, example: 'Joe Bloggs'
  end
end

2) Documentation Generator

From the DSL generated data structure, we want to produce the following markdown.

## POST `/api/posts`

Creates a post in the database

#### Success

'''json
{ "posts" : [ {
  "id"          : 1,
  "title"       : "Ruby is Great",
  "author_id"   : 2,
  "author_name" : "Joe Bloggs"
] }
'''

3) Mountable Rack application stubbing the endpoint

Take the data structure generated by the DSL, and mount it as a Rack application.

# ./config/routes.rb

namespace :api do
  mount_api_buddy 'api_docs/posts_endpoints'
end

4) Auto-generated tests for implemented API endpoints

# ./spec/requests/posts/post_create_spec.rb

describe "POST /api/posts" do
  with_api_buddy 'api_docs/posts_endpoints' do
    test_api_endpoint '/api/posts', method: :post
  end
end