apidoco 1.5.3 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a9ea1e632b75c735ae66f77004a3b1d5e812984c300964bb5703fca2090dea6
-  data.tar.gz: b5d7343289d59fa8967f6244093023f4477a3d88e3c0cd817a7c2ba30997bf15
+  metadata.gz: c0b95567a7f22f4808d803b0e23e619af3d69b1690c7e306a9813188ba84d41e
+  data.tar.gz: 6f9da62438399fefc699b63cded3bb6a0460f75e09e29a7b76050a02d710b563
 SHA512:
-  metadata.gz: aa0a75c9eff5ea3e39a0ad1e48db040b8ec66afd467eaeac696d5bf1ce4e6ce51cc11ff07b765ad313b78633da718e055144fb09d91fef337ee94e943a1a3346
-  data.tar.gz: 5c9484b56d85fcfbe6e94eaead507535504ebbca020d21f73ff8a18593ae96ee81088eb2e5d91e918c6de577ed779392d7a95764aea513642f6d406fb03d08ba
+  metadata.gz: e7f723f403eb60620a071a3a4264cf70b170362c08e38c5d16d17cdc1be66cc52bf555f1677816bcd04efb5ffad6703a7fc99a1d96818e9f8dc2ace195cb947a
+  data.tar.gz: 8e1a5631ea0c06fe08c79f17abb188e30e0621874cd2279809da3516c6719d4f30f94f9876cd077f92e3768405027675dc82b99e25876e6dc842e763b01d6855

data/README.md

@@ -7,8 +7,6 @@ Easy documentation of REST APIs - [Demo](https://apidoco-demo.herokuapp.com/docs
 
 ![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)
-
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -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,195 @@ 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"
+
+  "params": [
+    {
+      "key": "post[title]",
+      "required": true,
+      "type": "String",
+      "description": "Title of the post",
+      "validations": ["Should be less than or equal to 40 characters"]
     },
-    "request": {
-      "post": {
-        "title": "Ruby is awesome",
-        "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec interdum a tellus sed finibus.",
-        "published": false
-      }
+    {
+      "key": "post[content]",
+      "required": true,
+      "type": "String",
+      "description": "Content/Body of the post",
+      "validations": ["Should be less than or equal to 300 characters"]
     },
-    "response_headers": {
-      "Authentication": "Token token=<token>"
-    },
-    "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
+
+  "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"
+
+  "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"
+ ```
 
-| 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 } }]`
+ ### # 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'
+  }
+```
+
+### # 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/stylesheets/apidoco/custom.css

@@ -40,3 +40,34 @@ h3 {
   margin-top: 0;
 }
 
+.container-flex {
+  display: flex;
+  width: 100%;
+  position: relative;
+}
+
+.container-flex .description {
+  flex: 0 0 65%;
+}
+
+.container-flex .examples {
+  position: absolute;
+  left: 70%;
+  top: 0;
+  bottom: 0;
+  right: 0;
+  overflow: auto;
+}
+
+.built-with {
+  position: absolute;
+  bottom: 0;
+  left: 20%;
+  padding: 10px;
+  font-size: 12px;
+}
+
+.built-with a, .built-with a:hover {
+  color: white;
+}
+

data/app/assets/stylesheets/apidoco/helpers.css

@@ -11,7 +11,14 @@
   margin-top: 10px !important;
 }
 
+.mb-50 {
+  margin-bottom: 50px !important;
+}
+
 .padding-10 {
   padding: 10px !important;
 }
 
+.padding-15 {
+  padding: 15px !important;
+}

data/app/assets/stylesheets/apidoco/simple-sidebar.css

@@ -19,16 +19,16 @@
 }
 
 #wrapper.toggled {
-    padding-left: 275px;
+    padding-left: 225px;
 }
 
 #sidebar-wrapper {
     z-index: 1000;
     position: fixed;
-    left: 275px;
+    left: 225px;
     width: 0;
     height: 100%;
-    margin-left: -275px;
+    margin-left: -225px;
     overflow-y: auto;
     background: #364150;
     -webkit-transition: all 0.5s ease;
@@ -39,7 +39,7 @@
 }
 
 #wrapper.toggled #sidebar-wrapper {
-    width: 275px;
+    width: 225px;
 }
 
 #page-content-wrapper {
@@ -50,7 +50,7 @@
 
 #wrapper.toggled #page-content-wrapper {
     position: absolute;
-    margin-right: -275px;
+    margin-right: -225px;
 }
 
 /* Sidebar Styles */
@@ -105,7 +105,7 @@
 
 @media(min-width:768px) {
     #wrapper {
-        padding-left: 275px;
+        padding-left: 225px;
     }
 
     #wrapper.toggled {
@@ -113,7 +113,7 @@
     }
 
     #sidebar-wrapper {
-        width: 275px;
+        width: 225px;
     }
 
     #wrapper.toggled #sidebar-wrapper {