72pulses / apidoco

Ruby on Rails API documentation tool

Apidoco - Ruby on Rails API documentation tool

Easy documentation of REST APIs - Demo.

Screenshots

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"]
  }
]

# header

• 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
• Usage:

"examples": [
  {
    "request_headers": {
      "Authorization": "Token token=<token>",
      "Content-type": 'application/json'
    },

    "request": {
      "post": {
        "name": "I was scared"
      }
    },

    "response_headers": {
      "Content-type": 'application/json'
    },

    "response": {
      "message": "Post was successfully created",
      "id": 101
    }
  }
]

License

The gem is available as open source under the terms of the MIT License.

apidoco's Issues

New CSS theme

Sprockets::FileNotFound in Apidoco::Apis#show

couldn't find file 'angular/1.8.0/angular' with type 'application/javascript'

// about supported directives.
//
//= require angular/1.8.0/angular < ------- error
//
//= require apidoco/jquery.min
//= require apidoco/jquery.json-viewer

Alphabetical Ordering Of Endpoints

The endpoints are out of order, currently not being sorted alphabetically.

Is there an option to specify the ordering of endpoints?

Not loaded assets

This is error in console browser :

GET http://localhost:3000/stylesheets/apidoco/application.css net::ERR_ABORTED
GET http://localhost:3000/javascripts/apidoco/application.js net::ERR_ABORTED

Sidebar search not applying filter in child lists

Search option in sidebar is showing all child elements even if only one child matches the search keyword

Change The Page Title

The page title is currently hardcoded as Apidoco, it would be nice to override via a setting.

<head>
  <title>Apidoco</title>
  <%= stylesheet_link_tag "apidoco/application", media: "all" %>
  <%= javascript_include_tag "apidoco/application" %>
  <%= csrf_meta_tags %>
</head>

https://github.com/72pulses/apidoco/blob/master/app/views/layouts/apidoco/application.html.erb

ApiDoco::VersionParser

See https://github.com/alameenkhader/apidoco/issues/3

Documentation Version Parser

This is the milestone issue which focuses on building the following

• Rails generator to create the sample API documentation files and folders
• Classes to parse these version-ed documents

Directory structure for documentation

docs
---api
------v1
---------posts
------------create.json
------------list.json
------------show.json
------------update.json
------------delete.json
---------comments
------------create.json
------------delete.json
------v2
---------posts
------------create.json
------------list.json
------------show.json
------------update.json
------------delete.json
---------comments
------------create.json
------------delete.json

Classes

• Apidoco::Documentation - parsers all the files of the specified documentation folder(ex:- v1)
• ApiDoco::VersionParser - keeps track of all the Documentations(ex:- should have an array of all the Apidoco::Documentation versions)

Tasks

• Generator - https://github.com/alameenkhader/apidoco/issues/4
• Apidoco::Documentation - https://github.com/alameenkhader/apidoco/issues/5
• ApiDoco::VersionParser - https://github.com/alameenkhader/apidoco/issues/6

Fix vulnerability dependencies reported by github

https://github.com/72pulses/apidoco/network/alerts

Show in a line 'request' and 'response'

When listing several examples of request-response pairs, they are disordered and don't respect keeping each new pair on a line.

View:

Specifying the "direction" of the parameter.

I'd like to specify in the parameters for a request, or for a response to a request.

for example, to inform that the parameter is optional or to describe it.

In examples of requests, the essence of one or another parameter (in response to a request) may not always be clear.

Build documentation generator

See https://github.com/alameenkhader/apidoco/issues/3

Response Headers in Example

It looks like example can't include response headers
Is there a way to document the response headers?
There should be as for api auth responses.. i'm using devise_token_auth and they give the token info in the response headers.

[Question] Does this gem works on "api-only" mode?

I tried using the gem in and old project that uses the api only mode in rails but when I access the /docs route it shows just the HTML with angular tags. So... Does the gem work with this type of API?

It shows like this in my localhost

The project configs are:

• ruby: 2.4.9
• Rails: 4.2.3

Thanks for the attention!

Add description to parameter

How do I set the http response code?

It is necessary to reflect the http code in the examples of requests, how can this be done?

Test Coverage

• Set Up Rspec
• Cover Generators
• Feature Tests
• Unit Tests

.DS_Store files inside api folders screw with JSON parsing.

What a mission that was to figure out!
Especially due to .DS_Store files no longer showing in finder (even when showing dotfiles 🙄)
Not sure if this is really an issue, but worth noting anyway.

Thanks for the great gem!

Apidoco::Documentation

See https://github.com/alameenkhader/apidoco/issues/3

Filter APIs

• Angular DOM filtering