From af24e24d987a2326a4cb7f59709472b6f78ec5d7 Mon Sep 17 00:00:00 2001
From: Sebastian Abondano <sabondano1@gmail.com>
Date: Tue, 7 Aug 2018 15:45:36 -0400
Subject: [PATCH] Adds error example values to API docs page

Why:

* For users to be able to see an example of what errors might look like
when perusing the API's docs pages.
* Issue link: related to
https://github.com/poanetwork/poa-explorer/issues/138

This change addresses the need by:

* Editing `ExplorerWeb.Etherscan` to include "error" example values for
`account#balance`, `account#balancemulti`, and `account#txlist` calls.
Also, adding "description" field for responses.
* Editing `templates/api_docs/_action_tile.html.eex` to only render
model information for the first response in the responses table. Also,
rendering description field from the documentation data passed to the
template (from `ExplorerWeb.Etherscan`).
---
 .../lib/explorer_web/etherscan.ex             | 30 +++++++++++++
 .../templates/api_docs/_action_tile.html.eex  | 45 +++++++++++--------
 2 files changed, 56 insertions(+), 19 deletions(-)

diff --git a/apps/explorer_web/lib/explorer_web/etherscan.ex b/apps/explorer_web/lib/explorer_web/etherscan.ex
index 0435c75592..0d4b8807d4 100644
--- a/apps/explorer_web/lib/explorer_web/etherscan.ex
+++ b/apps/explorer_web/lib/explorer_web/etherscan.ex
@@ -9,6 +9,12 @@ defmodule ExplorerWeb.Etherscan do
     "result" => "663046792267785498951364"
   }
 
+  @account_balance_example_value_error %{
+    "status" => "0",
+    "message" => "Invalid address hash",
+    "result" => nil
+  }
+
   @account_balancemulti_example_value %{
     "status" => "1",
     "message" => "OK",
@@ -56,6 +62,12 @@ defmodule ExplorerWeb.Etherscan do
     ]
   }
 
+  @account_txlist_example_value_error %{
+    "status" => "0",
+    "message" => "No transactions found",
+    "result" => []
+  }
+
   @status_type %{
     type: "status",
     enum: ~s(["0", "1"]),
@@ -173,6 +185,7 @@ defmodule ExplorerWeb.Etherscan do
     responses: [
       %{
         code: "200",
+        description: "successful operation",
         example_value: Jason.encode!(@account_balance_example_value),
         model: %{
           name: "Result",
@@ -182,6 +195,11 @@ defmodule ExplorerWeb.Etherscan do
             result: @wei_type
           }
         }
+      },
+      %{
+        code: "200",
+        description: "error",
+        example_value: Jason.encode!(@account_balance_example_value_error)
       }
     ]
   }
@@ -202,6 +220,7 @@ defmodule ExplorerWeb.Etherscan do
     responses: [
       %{
         code: "200",
+        description: "successful operation",
         example_value: Jason.encode!(@account_balancemulti_example_value),
         model: %{
           name: "Result",
@@ -214,6 +233,11 @@ defmodule ExplorerWeb.Etherscan do
             }
           }
         }
+      },
+      %{
+        code: "200",
+        description: "error",
+        example_value: Jason.encode!(@account_balance_example_value_error)
       }
     ]
   }
@@ -262,6 +286,7 @@ defmodule ExplorerWeb.Etherscan do
     responses: [
       %{
         code: "200",
+        description: "successful operation",
         example_value: Jason.encode!(@account_txlist_example_value),
         model: %{
           name: "Result",
@@ -274,6 +299,11 @@ defmodule ExplorerWeb.Etherscan do
             }
           }
         }
+      },
+      %{
+        code: "200",
+        description: "error",
+        example_value: Jason.encode!(@account_txlist_example_value_error)
       }
     ]
   }
diff --git a/apps/explorer_web/lib/explorer_web/templates/api_docs/_action_tile.html.eex b/apps/explorer_web/lib/explorer_web/templates/api_docs/_action_tile.html.eex
index 63bb00dd6c..7a5139bef3 100644
--- a/apps/explorer_web/lib/explorer_web/templates/api_docs/_action_tile.html.eex
+++ b/apps/explorer_web/lib/explorer_web/templates/api_docs/_action_tile.html.eex
@@ -148,14 +148,14 @@
               </tr>
             </thead>
             <tbody>
-              <%= for response <- @action.responses do %>
+              <%= for {response, index} <- Enum.with_index(@action.responses) do %>
               <tr>
                 <td>
                   <%= response.code %>
                 </td>
                 <td>
                   <div class="card card-body bg-dark rounded p-0">
-                    <pre class="text-white m-2"><em>successful operation</em></pre>
+                    <pre class="text-white m-2"><em><%= response.description %></em></pre>
                   </div>
 
                   <ul class="nav nav-pills mb-3" role="tablist">
@@ -170,17 +170,20 @@
                          Example Value
                       </a>
                     </li>
-                    <li class="nav-item">
-                      <a class="nav-link"
-                         id="<%= "#{@module_name}-#{@action.name}-model-tab" %>"
-                         data-toggle="pill"
-                         href="#<%= "#{@module_name}-#{@action.name}-model" %>"
-                         role="tab"
-                         aria-controls="<%= "#{@module_name}-#{@action.name}-model" %>"
-                         aria-selected="false">
-                         Model
-                      </a>
-                    </li>
+
+                    <%= if index == 0 do %>
+                      <li class="nav-item">
+                        <a class="nav-link"
+                           id="<%= "#{@module_name}-#{@action.name}-model-tab" %>"
+                           data-toggle="pill"
+                           href="#<%= "#{@module_name}-#{@action.name}-model" %>"
+                           role="tab"
+                           aria-controls="<%= "#{@module_name}-#{@action.name}-model" %>"
+                           aria-selected="false">
+                           Model
+                        </a>
+                      </li>
+                    <% end %>
                   </ul>
                   <div class="tab-content">
                     <div class="tab-pane fade show active"
@@ -191,12 +194,16 @@
                            <pre class="text-white m-2" data-json='<%= response.example_value %>'></pre>
                          </div>
                     </div> <!-- /tab-pane -->
-                    <div class="tab-pane fade"
-                         id="<%= "#{@module_name}-#{@action.name}-model" %>"
-                         role="tabpanel"
-                         aria-labelledby="<%= "#{@module_name}-#{@action.name}-model-tab" %>">
-                         <%= render "_model_table.html", model: response.model %>
-                    </div> <!-- /tab-pane -->
+
+                    <%= if index == 0 do %>
+                      <div class="tab-pane fade"
+                           id="<%= "#{@module_name}-#{@action.name}-model" %>"
+                           role="tabpanel"
+                           aria-labelledby="<%= "#{@module_name}-#{@action.name}-model-tab" %>">
+                           <%= render "_model_table.html", model: response.model %>
+                      </div> <!-- /tab-pane -->
+                    <% end %>
+
                   </div> <!-- /tab-content -->
 
                 </td>