Ruby on Rails API documentation tool
Easy documentation of REST APIs - Demo.
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"
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 =
auth_name
and auth_password
to the config file.Apidoco.auth_name = 'authentication_name'
Apidoco.auth_password = 'authentication_password'
app_name
app_name
will be added to the sidebarApidoco.app_name = 'Apidoco Demo'
base_path
docs/api
Apidoco.base_path = 'documentations'
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
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/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"
}
}
]
}
"end_point": "/posts"
"http_method": "GET"
"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": {
"Authorization": "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."
}
],
"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
}
}
]
The gem is available as open source under the terms of the MIT License.