MDL-28650 add a page in the administration to the full web service AP…

…I (API documentation).

admin/settings/plugins.php

@@ -344,6 +344,8 @@
     $temp = new admin_settingpage('webservicesoverview', get_string('webservicesoverview', 'webservice'));
     $temp->add(new admin_setting_webservicesoverview());
     $ADMIN->add('webservicesettings', $temp);
+    //API documentation
+    $ADMIN->add('webservicesettings', new admin_externalpage('webservicedocumentation', get_string('wsdocapi', 'webservice'), "$CFG->wwwroot/$CFG->admin/webservice/documentation.php", 'moodle/site:config', false));
     /// manage service
     $temp = new admin_settingpage('externalservices', get_string('externalservices', 'webservice'));
     $enablemobiledocurl = new moodle_url(get_docs_url('Enable_mobile_web_services'));

admin/webservice/documentation.php

@@ -0,0 +1,61 @@
+<?php
+
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+/**
+ * Web services API documentation
+ *
+ * @package   webservice
+ * @copyright 2011 Moodle Pty Ltd (http://moodle.com)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @author Jerome Mouneyrac
+ */
+require_once('../../config.php');
+require_once($CFG->libdir . '/adminlib.php');
+require($CFG->dirroot . '/webservice/lib.php');
+
+admin_externalpage_setup('webservicedocumentation');
+
+// get all the function descriptions
+$functions = $DB->get_records('external_functions', array(), 'name');
+$functiondescs = array();
+foreach ($functions as $function) {
+    $functiondescs[$function->name] = external_function_info($function);
+}
+
+//display the documentation for all documented protocols,
+//regardless if they are activated or not
+$protocols = array();
+$protocols['rest'] = true;
+$protocols['xmlrpc'] = true;
+
+/// Check if we are in printable mode
+$printableformat = optional_param('print', false, PARAM_BOOL);
+
+/// OUTPUT
+echo $OUTPUT->header();
+
+$renderer = $PAGE->get_renderer('core', 'webservice');
+echo $renderer->documentation_html($functiondescs,
+        $printableformat, $protocols, array(), $PAGE->url);
+
+/// trigger browser print operation
+if (!empty($printableformat)) {
+    $PAGE->requires->js_function_call('window.print', array());
+}
+
+echo $OUTPUT->footer();
+

lang/en/webservice.php

@@ -195,6 +195,7 @@
 $string['wsauthmissing'] = 'The web service authentication plugin is missing.';
 $string['wsauthnotenabled'] = 'The web service authentication plugin is disabled.';
 $string['wsclientdoc'] = 'Moodle web service client documentation';
+$string['wsdocapi'] = 'API Documentation';
 $string['wsdocumentation'] = 'Web service documentation';
 $string['wsdocumentationdisable'] = 'Web service documentation is disabled.';
 $string['wsdocumentationintro'] = 'To create a client we advise you to read the {$a->doclink}';

webservice/renderer.php

@@ -598,11 +598,14 @@ public function rest_param_description_html($paramdescription, $paramstring) {
      * @param array $authparam keys contains 'tokenid'
      * @param boolean $printableformat true if we want to display the documentation in a printable format
      * @param array $activatedprotocol
+     * @param string $parenturl url of the calling page - needed for the print button url:
+     *               '/admin/documentation.php' or '/webservice/wsdoc.php' (default)
      * @return string the html to diplay
      */
-    public function documentation_html($functions, $printableformat, $activatedprotocol, $authparams) {
+    public function documentation_html($functions, $printableformat, $activatedprotocol,
+            $authparams, $parenturl = '/webservice/wsdoc.php') {
 
-        $documentationhtml = $this->output->heading(get_string('documentation', 'webservice'));
+        $documentationhtml = $this->output->heading(get_string('wsdocapi', 'webservice'));
 
         $br = html_writer::empty_tag('br', array());
         $brakeline = <<<EOF
@@ -625,7 +628,7 @@ public function documentation_html($functions, $printableformat, $activatedproto
         /// Print button
         $authparams['print'] = true;
         //$parameters = array ('token' => $token, 'wsusername' => $username, 'wspassword' => $password, 'print' => true);
-        $url = new moodle_url('/webservice/wsdoc.php', $authparams); // Required
+        $url = new moodle_url($parenturl, $authparams); // Required
         $documentationhtml .= $this->output->single_button($url, get_string('print', 'webservice'));
         $documentationhtml .= $br;
 

webservice/wsdoc.php

@@ -73,10 +73,7 @@
 $activatedprotocol['xmlrpc'] = webservice_protocol_is_enabled('xmlrpc');
 
 /// Check if we are in printable mode
-$printableformat = false;
-if (isset($_REQUEST['print'])) {
-    $printableformat = $_REQUEST['print'];
-}
+$printableformat = optional_param('print', false, PARAM_BOOL);
 
 /// OUTPUT
 echo $OUTPUT->header();