MDL-81031 admin: Add swagger UI

admin/settings/development.php

@@ -109,6 +109,15 @@ if ($hassiteconfig) { // speedup for non-admins, add all caps used on this page
     // Add the 'profiling' page to admin block.
     $ADMIN->add('development', $temp);
 
+    $ADMIN->add(
+        parentname: 'development',
+        something: new admin_externalpage(
+            name: 'swaggerui',
+            visiblename: new lang_string('swaggerui', 'admin'),
+            url: "$CFG->wwwroot/admin/swaggerui.php",
+        ),
+    );
+
     // Web service test clients DO NOT COMMIT : THE EXTERNAL WEB PAGE IS NOT AN ADMIN PAGE !!!!!
     $ADMIN->add('development', new admin_externalpage('testclient', new lang_string('testclient', 'webservice'), "$CFG->wwwroot/$CFG->admin/webservice/testclient.php"));
 

admin/swaggerui.php

@@ -0,0 +1,87 @@
+<?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/>.
+
+/**
+ * Swagger UI for Moodle
+ *
+ * @package   core_admin
+ * @copyright Andrew Lyons <andrew@nicols.co.uk>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+require('../config.php');
+require_once($CFG->libdir . '/adminlib.php');
+
+$swaggerversion = '5.17.14';
+
+$PAGE->set_url('/admin/swaggerui.php');
+
+admin_externalpage_setup('swaggerui');
+
+$PAGE->requires->css(new moodle_url("https://unpkg.com/swagger-ui-dist@{$swaggerversion}/swagger-ui.css"));
+
+echo $OUTPUT->header();
+
+// These have to be manually added for now because they must be made cross-origin. The `js` method does not yet support this.
+echo html_writer::tag(
+    tagname: 'script',
+    contents: '',
+    attributes: [
+        'src' => new moodle_url("https://unpkg.com/swagger-ui-dist@{$swaggerversion}/swagger-ui-bundle.js"),
+        'crossorigin' => 'crossorigin',
+    ],
+);
+echo html_writer::tag(
+    tagname: 'script',
+    contents: '',
+    attributes: [
+        'src' => new moodle_url("https://unpkg.com/swagger-ui-plugin-hierarchical-tags"),
+        'crossorigin' => 'crossorigin',
+    ],
+);
+
+$openapipath = moodle_url::routed_path('/api/rest/v2/openapi.json')->out();
+$swaggerinit = <<<JS
+    window.ui = SwaggerUIBundle({
+        url: "{$openapipath}",
+        dom_id: '#swagger-ui',
+
+        // Enable the "Try it out" button by default.
+        tryItOutEnabled: true,
+
+        // Show snippets different OS options.
+        requestSnippetsEnabled: true,
+
+        deepLinking: true,
+
+        plugins: [
+            HierarchicalTagsPlugin,
+        ],
+
+        hierarchicalTagSeparator: /[_]/
+    });
+JS;
+
+$PAGE->requires->js_init_code(
+    jscode: $swaggerinit,
+    ondomready: true,
+);
+
+echo html_writer::div('', '', [
+    'id' => 'swagger-ui',
+]);
+
+echo $OUTPUT->footer();

config-dist.php

@@ -180,6 +180,14 @@ $CFG->wwwroot   = 'http://example.com/moodle';
 
 $CFG->dataroot  = '/home/example/moodledata';
 
+// Whether the Moodle router is fully configured.
+//
+// From Moodle 4.5 this is set to false.
+// The default value will change in a future release.
+//
+// When not configured on the web server it must be accessed via https://example.com/moodle/r.php
+// When configured the on the web server the 'r.php' may be removed.
+$CFG->routerconfigured = false;
 
 //=========================================================================
 // 4. DATA FILES PERMISSIONS

lang/en/admin.php

@@ -1354,6 +1354,7 @@ $string['supportemailsubject'] = 'Site support request - {$a}';
 $string['supportavailability'] = 'Support availability';
 $string['supportname'] = 'Support name';
 $string['supportpage'] = 'Contact site support link';
+$string['swaggerui'] = 'Moodle REST API UI (SwaggerUI)';
 $string['suspenduser'] = 'Suspend user account';
 $string['switchlang'] = 'Switch lang directory';
 $string['systempaths'] = 'System paths';

lib/classes/url.php

@@ -622,6 +622,28 @@ class url {
         return $url;
     }
 
+    /**
+     * Create a new moodle_url instance from routed path.
+     *
+     * @param string $path The routed path
+     * @param null|array $params The path parameters
+     * @param null|string $anchor The anchor
+     * @return self
+     */
+    public static function routed_path(
+        string $path,
+        ?array $params = null,
+        ?string $anchor = null,
+    ): self {
+        global $CFG;
+
+        if (!$CFG->routerconfigured) {
+            $path = '/r.php/' . ltrim($path, '/');
+        }
+        $url = new self($path, $params, $anchor);
+        return $url;
+    }
+
     /**
      * General moodle file url.
      *

lib/setup.php

@@ -196,6 +196,9 @@ if (!isset($CFG->wwwroot) or $CFG->wwwroot === 'http://example.com/moodle') {
     exit(1);
 }
 
+// The router configuration is mandatory.
+$CFG->routerconfigured = !empty($CFG->routerconfigured);
+
 // Make sure there is some database table prefix.
 if (!isset($CFG->prefix)) {
     $CFG->prefix = '';

lib/tests/url_test.php

@@ -669,4 +669,21 @@ final class url_test extends \advanced_testcase {
             ],
         ];
     }
+
+    /**
+     * Test that URL routed paths are generated correctly depending on the value of $CFG->routerconfigured.
+     */
+    public function test_routed_path(): void {
+        global $CFG;
+
+        $this->resetAfterTest();
+
+        $CFG->routerconfigured = false;
+        $url = url::routed_path('/example');
+        $this->assertSame('/r.php/example', $url->out_as_local_url(false));
+
+        $CFG->routerconfigured = true;
+        $url = url::routed_path('/example');
+        $this->assertSame('/example', $url->out_as_local_url(false));
+    }
 }