apidoco 1.5.6 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e3d3454ddc778794cd54370eaa81246d6fc10701f25cbb598b63d1c7660dbab
-  data.tar.gz: add5252b311eef0cb55987e1fd595fa3ffce9b14f19991bf5ceabc321405e99d
+  metadata.gz: 66ecb5cbf00cf49220d007d6c7fa3a59629743567ae3ea52c8fc4af827f278cb
+  data.tar.gz: b081bd28fe33bf7e33e9d6d26034b7b3d848d4be2356bf75ca39ef5ac37ae82b
 SHA512:
-  metadata.gz: c1dbd0735e3bbef5d25a9be6bbfd4b9623e846c43854909b5caf6968c2cd63d12be6098739ec5a7287af26454c4d54894f5c856aab94dde6a571826ac7d13df2
-  data.tar.gz: 886772bcf39b54fdbdecf01506340ef80aaf3f003cda625ee39556d0b1b60bae3d9ee389edafa6429aaa2ef5067b5de9d1fcaba8e534db48cb1a38c12c6c92e7
+  metadata.gz: 3c97695998cb86bcf8148ca374a2eddee2f817cee46a42ceb10294d261fcfdd57441e2d6de24f48ddad8aacc6b4d973d48ac3cdc4dd374a9cedd03e5c8f81f57
+  data.tar.gz: ebd99d4e4989ba72266e47642792818d2f6b9511465171875ab6a05d516585d16e6887325a53beebe98c6fad4aad4346bd4abe74d38fd3900a2f9d183fbfb54e

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,8 +63,7 @@ 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
 ```
@@ -60,9 +77,7 @@ will create the following files by default with sample content
 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
-```
+```ruby
 rails g apidoco api/v1/posts download upload
 ```
 will create the following files with sample content
@@ -75,148 +90,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

@@ -59,4 +59,15 @@ h3 {
   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/views/apidoco/apis/_side_bar.html.erb

@@ -11,7 +11,7 @@
   <ul class="sidebar-nav">
     <li class="sidebar-brand">
       <a href="#">
-        APIDOCO::{{currentVersion}}
+        <%= Apidoco.app_name %>
       </a>
     </li>
     <li class="padding-10">
@@ -25,4 +25,9 @@
     <li ng-repeat="documentation in data.apis | filter: searchKeyword" ng-include="'documentationTree'">
     </li>
   </ul>
+
+  <div class="built-with">
+    Built with <a href="https://github.com/72pulses/apidoco" target="blank">ApiDoco</a>
+  </div>
 </div>
+

data/lib/apidoco/file_parser.rb

@@ -13,7 +13,7 @@ module Apidoco
     end
 
     def content
-      JSON.parse(File.read(file))
+      @content ||= JSON.parse(File.read(file))
     end
 
     def id

data/lib/apidoco/version.rb

@@ -1,3 +1,3 @@
 module Apidoco
-  VERSION = '1.5.6'
+  VERSION = '1.6.0'.freeze
 end

data/spec/apidoco/file_parser_spec.rb

@@ -0,0 +1,57 @@
+require 'rails_helper'
+
+describe Apidoco::FileParser do
+  let(:doc) { { name: 'Create Resource' } }
+  let(:file) do
+    Tempfile.new.tap do |f|
+      f.write(doc.to_json)
+      f.rewind
+    end
+  end
+  let(:file_parser) { described_class.new(file, parents: []) }
+
+  after do
+    file.close
+    file.unlink
+  end
+
+  describe '#id' do
+    subject(:id) { file_parser.id }
+
+    it { is_expected.to eq('createresource') }
+  end
+
+  describe '#published?' do
+    subject(:published?) { file_parser.published? }
+
+    context 'when published key is not available in the doc' do
+      it { is_expected.to eq true }
+    end
+
+    context 'when published key is true in the doc' do
+      let(:doc) { { published: true } }
+
+      it { is_expected.to eq true }
+    end
+
+    context 'when published key is false in the doc' do
+      let(:doc) { { published: false } }
+
+      it { is_expected.to eq false }
+    end
+  end
+
+  describe '#sort_order' do
+    subject(:sort_order) { file_parser.sort_order }
+
+    context 'when sort_order key is not available in the doc' do
+      it { is_expected.to eq 999 }
+    end
+
+    context 'when sort_order key is available in the doc' do
+      let(:doc) { { sort_order: 25 } }
+
+      it { is_expected.to eq 25 }
+    end
+  end
+end