[enh] starting to self-document

api/panel/index.php

@@ -193,24 +193,4 @@ if (preg_match("#^/api/rest/([^/]*)/([^/\?]*)[/\?]?#", $_SERVER["REQUEST_URI"],
     }
 }
 
-function doc($data) {
-    global $dbh;
-    $options["databaseAdapter"] = $dbh;
-    try {
-        $service = new Alternc_Api_Service($options);
-
-        $response = $service->documentation($data);
-        return $response;
-    } catch (Exception $e) {
-        // something went wrong, we spit out the exception as an Api_Response
-        // TODO : Don't do that on production! spit out a generic "fatal error" code and LOG the exception !
-        header("Content-Type: application/json");
-        $response = new Alternc_Api_Response(array("code" => $e->getCode(), "message" => $e->getMessage()));
-        echo $response->toJson();
-        exit();
-    }
-}
-
-doc("auth/login");
-
 echo "I did nothing. Did you call the api properly?";

lib/Alternc/Api/Auth/Interface.php

@@ -19,8 +19,8 @@ interface Alternc_Api_Auth_Interface {
     function auth($options);
 
     /**
-     * Api Documentation
+     * instructions on how to use this Auth class
      * @return array("fields" => array("fields to send, required or not"), "description" => "description of this auth")
      */
-    function documentation();
+    function instructions();
 }

lib/Alternc/Api/Auth/Login.php

@@ -57,10 +57,10 @@ class Alternc_Api_Auth_Login implements Alternc_Api_Auth_Interface {
     }
 
     /**
-     * Api Documentation
+     * instructions on how to use this Auth class
      * @return array("fields" => array("fields to send, required or not"), "description" => "description of this auth")
      */
-    function documentation() {
+    function instructions() {
         return array("fields" => array("login" => "AlternC user account", "password" => "AlternC's user password stored in membres table."),
             "description" => "Authenticate against an AlternC user and password, the same as for the control panel"
         );

lib/Alternc/Api/Auth/Sharedsecret.php

@@ -65,10 +65,10 @@ class Alternc_Api_Auth_Sharedsecret implements Alternc_Api_Auth_Interface {
     }
 
     /**
-     * Api Documentation
+     * instructions on how to use this Auth class
      * @return array("fields" => array("fields to send, required or not"), "description" => "description of this auth")
      */
-    function documentation() {
+    function instructions() {
         return array("fields" => array("login" => "AlternC user account", "secret" => "API Key, Shared secrets, valid for this account, stored in sharedsecret table."),
             "description" => "Authenticate against an Api Key, also called SharedSecret. distinct from the account's password, can be plenty and revoked independently"
         );

lib/Alternc/Api/Service.php

@@ -183,6 +183,33 @@ class Alternc_Api_Service {
         }
     }
 
+    /**
+     * Return documentation of the API, either general (no parameters) 
+     * or for a specific action or auth class
+     * @param string $element the name of the object for which documentation is requested
+     * @return array a documentation hash (key/value)
+     */
+    function doc($element) {
+        if (substr($element, 0, 5) == "auth/") {
+            $adapterName = "Alternc_Api_Auth_" . ucfirst(strtolower(substr($element, 5)));
+            if (!class_exists($adapterName))
+                return false;
+            $authAdapter = new $adapterName($this);
+            return $authAdapter->documentation();
+        } else {
+            list($class, $action) = explode("/", $element);
+            $className = "Alternc_Api_Object_" . ucfirst(strtolower($class));
+            if (!class_exists($className))
+                return false;
+            $object = new $className($this);
+            if (!$action) {
+                return $authAdapter->documentation();
+            } else {
+                return $authAdapter->documentation($action);
+            }
+        }
+    }
+
     /**
      * Getter for the databaseAdapter 
      * (used by authAdapter)