Apidoco - Ruby on Rails API documentation tool

Easy documentation of REST APIs - Demo.

Screenshots

screeshot 1

Installation

Add this line to your application's Gemfile:

gem 'apidoco'

And then execute:

$ bundle

Add this line to your routes:

mount Apidoco::Engine, at: "/docs"

Configuring

Create a configuration file in initializers e.g. /config/initializers/apidoco.rb and add the following.

Apidoco.auth_name = 'authentication_name'
Apidoco.auth_password = 'authentication_password'
Apidoco.app_name = 'your app name'
Apidoco.base_path =

# Basic Http Authentication

To add basic http authentication add the auth_name and auth_password to the config file. Apidoco.auth_name = 'authentication_name' Apidoco.auth_password = 'authentication_password'

# `app_name`

The app_name will be added to the sidebar Apidoco.app_name = 'Apidoco Demo'

# `base_path`

Sets the root folder for the documentation
Default: docs/api Apidoco.base_path = 'documentations'

Generators

To create a Api documentation file for an action:

rails g apidoco resource

For Example:

rails g apidoco v1/posts

will create the following files by default with sample content

docs/api/v1/posts/show.json
docs/api/v1/posts/create.json
docs/api/v1/posts/update.json
docs/api/v1/posts/destroy.json
docs/api/v1/posts/index.json

The root path will be based on the base_path config.

If you need to create Api documention file for actions other than default crud actions, you need to specify the actions for which the files need to be generated

rails g apidoco v1/posts download upload

will create the following files with sample content

docs/api/v1/posts/download.json
docs/api/v1/posts/upload.json

Sample API documentation format

// docs/api/v1/posts/create.json
{
  "published": true,

  "name": "Create",

  "sort_order": 1,

  "end_point": "api/v1/posts/:id.json",

  "http_method": "POST",

  "params": [
    {
      "key": "post[title]",
      "required": true,
      "type": "String",
      "description": "Title of the post",
      "validations": ["Should be less than or equal to 40 characters"]
    },
    {
      "key": "post[content]",
      "required": true,
      "type": "String",
      "description": "Content/Body of the post",
      "validations": ["Should be less than or equal to 300 characters"]
    },
    {
      "key": "post[publsihed]",
      "required": true,
      "type": "Boolean",
      "description": "Published status of the post"
    }
  ],

  "header": {
    "Authentication": "Token token=<token>",
    "Content-Type": "application/json"
  },

  "response_properties": [
    {
      "key": "success",
      "type": "Boolean"
    }, {
      "key": "message",
      "type": "String",
      "description": "It can be any generic message. Examples:- Successfully created, Missing properties - title, content"
    }
  ],

  "examples": [
    {
      "request_headers": {
        "Authentication": "Token token=<token>",
        "Content-Type": "application/json"
      },

      "request": {
        "post": {
          "title": "Ruby is awesome",
          "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec interdum a tellus sed finibus.",
          "published": false
        }
      },

      "response_headers": {
        "Authentication": "Token token=<token>"
      },

      "response": {
        "suceess": true,
        "message": "Successfully created"
      }
    }
  ]
}

//docs/api/v1/posts/delete.json
{
  "published": true,

  "name": "Destroy Post",

  "sort_order": 6,

  "end_point": "api/v1/posts/:id.json",

  "http_method": "DELETE",

  "header": {
    "Authentication": "Token token=<token>",
    "Content-Type": "application/json"
  },

  "response_properties": [
    {
      "key": "success",
      "type": "Boolean"
    }, {
      "key": "message",
      "type": "String",
      "description": "It can be any generic message. Examples:- Successfully created, Missing properties - title, content"
    }
  ],

  "examples": [
    {
      "request_headers": {
        "Authentication": "Token token=<token>",
        "Content-Type": "application/json"
      },

      "response": {
        "suceess": true,
        "message": "Successfully destroyed"
      }
    }
  ]
}

Documentation format reference

# published

Set this to false if you do not want to list this api
Optional
Default: true

# name

Name of the api
Required

# sort_order

Order of the api to be listed
Optional

### # end_point

Required
Usage: "end_point": "/posts"

# http_method

The HTTP method of the API
Required
Usage: "http_method": "GET"

### # params

Parameters to be used
Optional

Usage:

"params": [
{
"key": "post['name']",

"required": true,

"type": "String",

"notes": ["Name or title of the post"],

"validations": ["should be less than or equal to 150 characters"]
}
]

headers to be used
Optional
Usage: "header": { "Authorization": "Token token=<token>", "Content-type": 'application/json' }

# response_properties

Describing the properties in the response body
Optional
Usage: "response_properties": [ { "key": "success", "type": "Boolean" }, { "key": "message", "type": "String", "description": "It can be any generic message. Examples:- Successfully created." } ],

# examples

Array of sample requests, responses and their headers
Optional