https://github.com/brett-richardson/api-buddy

Ruby DSL for documenting, stubbing & testing JSON APIs
https://github.com/brett-richardson/api-buddy

Last synced: 12 days ago
JSON representation

Ruby DSL for documenting, stubbing & testing JSON APIs

• Host: GitHub
• URL: https://github.com/brett-richardson/api-buddy
• Owner: brett-richardson
• License: mit
• Created: 2015-06-28T19:06:04.000Z (over 9 years ago)
• Default Branch: master
• Last Pushed: 2015-06-28T22:03:19.000Z (over 9 years ago)
• Last Synced: 2024-11-11T00:28:53.457Z (2 months ago)
• Language: Ruby
• Size: 137 KB
• Stars: 1
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: Readme.md
  • License: MIT-LICENSE

Awesome Lists containing this project

README

        
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.

```ruby

# ./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.

```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.

```ruby

# ./config/routes.rb

namespace :api do

  mount_api_buddy 'api_docs/posts_endpoints'

end

```

### 4) Auto-generated tests for implemented API endpoints

```ruby

# ./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

```