From 9ea88c2ce0eb06aef7de28e8a54e52b2bead2cb2 Mon Sep 17 00:00:00 2001
From: Simon Redfern <simon@tesobe.com>
Date: Thu, 5 Nov 2015 12:56:20 +0100
Subject: [PATCH] Updating documentation on the Resource Docs call

---
 .../scala/code/api/v1_4_0/APIMethods140.scala     | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/main/scala/code/api/v1_4_0/APIMethods140.scala b/src/main/scala/code/api/v1_4_0/APIMethods140.scala
index be2a9ebae..7b674fe19 100644
--- a/src/main/scala/code/api/v1_4_0/APIMethods140.scala
+++ b/src/main/scala/code/api/v1_4_0/APIMethods140.scala
@@ -302,13 +302,24 @@ trait APIMethods140 extends Loggable with APIMethods130 with APIMethods121{
       "GET",
       "/resource-docs/obp",
       "Get Resource Documentation in OBP format.",
-      "Returns documentation about the resources on this server including example body for POST or PUT requests.",
+      """Returns documentation about the RESTful resources on this server including example body for POST or PUT requests.
+        | Thus the OBP API Explorer (and other apps) can display and work with the API documentation.
+        | In the future this information will be used to create Swagger and RAML files.
+        |<ul>
+        |<li> operation_id is concatenation of version and function and should be unque (the aim of this is to allow links to code) </li>
+        |<li> version references the version that the API call is defined in.</li>
+        |<li> function is the (scala) function.</li>
+        |<li> request_url is empty for the root call, else the path.</li>
+        |<li> summary is a short description inline with the swagger terminology. </li>
+        |<li> description can contain html markup.</li>
+        |</ul>
+        """,
       emptyObjectJson,
       emptyObjectJson,
       emptyObjectJson :: Nil
     )
 
-    // Provides resource documents so that live docs (currently on Sofi) can display API documentation
+    // Provides resource documents so that API Explorer (or other apps) can display API documentation
     lazy val getResourceDocs : PartialFunction[Req, Box[User] => Box[JsonResponse]] = {
       case "resource-docs" :: "obp" :: Nil JsonGet _ => {
         user => {