BananaDocs

This gem will provide a simple way to build documentation for API project

This gem is not a generic gem yet.For while, it's specific for CDA-API project :(, sorry.

Installation

Add this line to your application's Gemfile:

gem 'banana_docs'

And then execute:

$ bundle

Or install it yourself as:

$ gem install banana_docs

Usage

After install the gem in your project, you need to create a file where you will write you documentation. For example, in folder doc create a file called index.slim. Write your documentation using the gem's helpers. And then, execute this in your terminal:

$ banana doc/index.slim public/documentation

This will generate documentation.

Helpers

To create a new section in documentation:

section(name)

= section 'Publishing new books'

To inform what this action do, your URL and METHOD:

action(title, options)

= action 'Publish new book', method: 'GET', url: '/some/url/path'

To add a table with params to send to API:

params(&block)

  = params
    = [...]

Inside the params method, you need to add some param helpers to build the table:

param(name, description, type, format, options = {})

  = params
    = param :name, 'Name of Book', :string, 'Just String', { required: false/true, obs: 'Here goes the description' }

Showing response:

response(&block)

  = response
    = [...]

To use a blockquote to inform some observation about an action:

note(text)

  = response
    = note 'Here some observarion about an action :P'

To informe the status code for response:

status_code(status) (200, 400 or 404)

  = response
    = status_code '200'

To show up how the code will be returned:

code(&block)

  = response
    = code
      = [...]

To Build and Hash for response:

key_with_block(name, &block)

  = response
    = code
      = key_with_block 'errors'

To add keys and values to hash returned for response:

key_value(key, value, show_keys = true)

  = response
    = code
      = key_with_block 'errors'
        = key_value 'attribute', '["error_type"]', false/true

When some empty Array is returned from response:

empty

  = response
    = status_code '200'
    = code
      = key_with_block 'addresses'
        = empty

To build your navigation menu (menu is based in all section itens):

show_nav_menu

  = show_nav_menu

To include assets in header:

include_assets

  = include_assets