apidoco 1.5.6 → 1.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e3d3454ddc778794cd54370eaa81246d6fc10701f25cbb598b63d1c7660dbab
-  data.tar.gz: add5252b311eef0cb55987e1fd595fa3ffce9b14f19991bf5ceabc321405e99d
+  metadata.gz: 97216befd2275515cd9bca242190941db31bb475c6031e056b839bb9bd2d29fa
+  data.tar.gz: 94179ffcd263c8e6ce4a6fd0f53f94251055cc267298e373f2cb2726af15d67e
 SHA512:
-  metadata.gz: c1dbd0735e3bbef5d25a9be6bbfd4b9623e846c43854909b5caf6968c2cd63d12be6098739ec5a7287af26454c4d54894f5c856aab94dde6a571826ac7d13df2
-  data.tar.gz: 886772bcf39b54fdbdecf01506340ef80aaf3f003cda625ee39556d0b1b60bae3d9ee389edafa6429aaa2ef5067b5de9d1fcaba8e534db48cb1a38c12c6c92e7
+  metadata.gz: 5af6ed9b2b1b9ee56d2c54e4f4ef8f977c3f2487bd54855758cc655f74507fa23e7a39bb89e9505a0f0bf45bf1b6eae53af1221f4999724a42874b0cffe123c4
+  data.tar.gz: 02b8546770931595463c1dbef731eb650372575a28e077a35d7f52a1661903bd71d84eb47876631abe8f953597ce8d6bb508db5b38742ccc2ef3891106472c19

data/README.md

@@ -1,13 +1,11 @@
 [![Gem Version](https://badge.fury.io/rb/apidoco.svg)](https://badge.fury.io/rb/apidoco)
 
 # Apidoco - Ruby on Rails API documentation tool
-Easy documentation of REST APIs - [Demo](https://apidoco-demo.herokuapp.com/docs/).
+Easy documentation of REST APIs - [Demo](http://demo.apidoco.com/docs/).
 
 ## Screenshots
 
-![screeshot 1](https://github.com/72pulses/apidoco/blob/master/images/1.jpg?raw=true)
-
-![screeshot 2](https://github.com/72pulses/apidoco/blob/master/images/2.jpg?raw=true)
+![screeshot 1](https://github.com/72pulses/apidoco/blob/master/images/1.png?raw=true)
 
 
 ## Installation
@@ -28,14 +26,34 @@ Add this line to your routes:
 mount Apidoco::Engine, at: "/docs"
 ```
 
-## How to add authentication
+## Configuring
 
 Create a configuration file in initializers e.g. /config/initializers/apidoco.rb and add the following.
 
 ```ruby
 Apidoco.auth_name = 'authentication_name'
 Apidoco.auth_password = 'authentication_password'
-Apidoco.app_name = 'your app name' # This will appear as the HTML title for api_doco pages
+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
@@ -45,10 +63,9 @@ To create a Api documentation file for an action:
 ```ruby
 rails g apidoco resource
 ```
-For Eg:
-ruby
+For Example:
 ```
-rails g apidoco api/v1/posts
+rails g apidoco v1/posts
 ```
 will create the following files by default with sample content
 - docs/api/v1/posts/show.json
@@ -57,13 +74,13 @@ will create the following files by default with sample content
 - 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
 
-For Eg:
-ruby
-```
-rails g apidoco api/v1/posts download upload
+```ruby
+rails g apidoco v1/posts download upload
 ```
 will create the following files with sample content
 - docs/api/v1/posts/download.json
@@ -75,148 +92,234 @@ 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"
-  },
-  "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
-      }
+
+  "params": [
+    {
+      "key": "post[title]",
+      "required": true,
+      "type": "String",
+      "description": "Title of the post",
+      "validations": ["Should be less than or equal to 40 characters"]
     },
-    "response_headers": {
-      "Authentication": "Token token=<token>"
+    {
+      "key": "post[content]",
+      "required": true,
+      "type": "String",
+      "description": "Content/Body of the post",
+      "validations": ["Should be less than or equal to 300 characters"]
     },
-    "response": {
-      "suceess": true,
-      "message": "Successfully created"
+    {
+      "key": "post[publsihed]",
+      "required": true,
+      "type": "Boolean",
+      "description": "Published status of the post"
     }
-  }]
-}
-```
+  ],
 
-```
-// docs/api/v1/posts/update.json
-{
-  "published": true,
-  "name": "Update",
-  "sort_order": 2,
-  "end_point": "api/v1/posts/:id.json",
-  "http_method": "PUT|PATCH",
-  "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"
   },
-  "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_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"
       }
-    },
-    "response_headers": {
-      "Content-Type": "application/json"
-    },
-    "response": {
-      "suceess": true,
-      "message": "Successfully updated"
     }
-  }]
+  ]
 }
-
 ```
 
 ```
 //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"
   },
-  "examples": [{
-    "request_headers": {
-      "Authentication": "Token token=<token>",
-      "Content-Type": "application/json"
-    },
-    "response": {
-      "suceess": true,
-      "message": "Successfully destroyed"
+
+  "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
 
-| Key | Description | Default | Example |
-| --- | --- | --- | --- |
-| `published` | Set this to false if you do not want to list this api | `true` | -- |
-| `name` | Name of the api | --- | --- |
-| `sort_order` | Order of the api to be listed | --- | --- |
-| `end_point` | --- | --- | `"end_point": "/posts"` |
-| `http_method` | The HTTP method of the API | --- | `"http_method": "GET"` |
-| `params` | Parameters to be used | --- | `"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 | --- | `"header: { "Authorization": "Token token=<token>", "Content-type": 'application/json' }"` |
-| `examples` | Array of sample requests, responses and their headers | --- | `[{ "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 } }]`
+### # 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](http://opensource.org/licenses/MIT).

data/app/assets/javascripts/apidoco/application.js

@@ -10,13 +10,26 @@
 // Read Sprockets README (https://github.com/rails/sprockets#sprockets-directives) for details
 // about supported directives.
 //
-//= require angular
+//= require angular/1.8.0/angular
 //
 //= require apidoco/jquery.min
 //= require apidoco/jquery.json-viewer
-//= require apidoco/bootstrap/bootstrap.min
+//= require apidoco/bootstrap/bootstrap
 //= require apidoco/clipboard.min
 //= require apidoco/directives/ngclipboard
 //= require apidoco/apidoco_app
+//
+//  Icons
+//= require apidoco/icons/linkIcon
+//= require apidoco/icons/copyIcon
+//= require apidoco/icons/redirectIcon
+//
+//= Components
+//= require apidoco/components/tabbed/ad-tabbed
+//= require apidoco/components/tabbed/headers/ad-headers
+//= require apidoco/components/tabbed/body-properties/ad-body-properties
+//= require apidoco/components/tabbed/example-headers/ad-example-headers
+//= require apidoco/components/tabbed/example-body/ad-example-body
+//
 //= require apidoco/directives/jq_json_viewer
 //= require apidoco/controllers/documentations_controller