Merge ~lloydwaltersj/maas:oapi-html-docs into maas:master

[Jack Lloyd-Walters]

Generate html docs from oapi spec

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-html-docs lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/260/consoleText
COMMIT: 4a035f2be920bbf379dd4b853d1dc12661b3642d

review: Needs Fixing

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-html-docs lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/261/consoleText
COMMIT: 4a035f2be920bbf379dd4b853d1dc12661b3642d

review: Needs Fixing

aa518d8... by Jack Lloyd-Walters on 2022-08-03

move JS dependencies out of maas

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-html-docs lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/262/consoleText
COMMIT: aa518d85234b54d71ab852e958465a0b08d9f449

review: Needs Fixing

47f294d... by Jack Lloyd-Walters on 2022-08-03

run linting

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-html-docs lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/263/consoleText
COMMIT: 47f294dd342164c1ea3782ab2c8e3bc9c5afa703

review: Needs Fixing

5c19028... by Jack Lloyd-Walters on 2022-08-04

testing jenkins

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-html-docs lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/265/consoleText
COMMIT: 5c19028f007e13054e22ce8ffa1b5795ad47265b

review: Needs Fixing

ede1fc1... by Jack Lloyd-Walters on 2022-08-04

fix test

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-html-docs lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: ede1fc119d3f9a71fa48238bbc599176b999e075

review: Approve

[Alberto Donato (ack)]

LGTM, one minor comment inline

review: Approve

cca21cb... by Jack Lloyd-Walters on 2022-08-04

change to comment

[MAAS Lander (maas-lander)]

UNIT TESTS
-b oapi-html-docs lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: cca21cb74427cddb474abf5df90ee96b88d2a16d

review: Approve

diff --git a/src/maasserver/api/doc_oapi.py b/src/maasserver/api/doc_oapi.py
index 9e7c55f..36793e2 100644
--- a/src/maasserver/api/doc_oapi.py
+++ b/src/maasserver/api/doc_oapi.py
@@ -19,9 +19,35 @@ from maasserver.api.annotations import APIDocstringParser
 from maasserver.api.doc import find_api_resources, generate_doc
 from maasserver.djangosettings import settings
 from maasserver.models.config import Config
+from maasserver.models.controllerinfo import get_maas_version
 from maasserver.utils import build_absolute_uri
 
 
+def openapi_docs_context(request):
+    """Return the aadditional context needed for the oapi doc template to function"""
+    colourmap = {
+        "bark": "#585841",
+        "blue": "#0060bf",
+        "magenta": "#974097",
+        "olive": "#3d5f11",
+        "prussian green": "#225d5c",
+        "purple": "#7764d8",
+        "red": "#a71b33",
+        "sage": "#4e5f51",
+        "viridian": "#025a3d",
+    }
+    local_server = _get_maas_servers()[0]
+    context = {
+        "openapi_url": local_server["url"] + "openapi.yaml",
+        "maas_colour": colourmap.get(
+            Config.objects.get_config("theme").lower(), "#262626"
+        ),
+        "maas_name": local_server["description"].removesuffix(" API"),
+        "maas_version": get_maas_version(),
+    }
+    return context
+
+
 def landing_page(request):
     """Render a landing page with pointers for the MAAS API.
 
@@ -71,7 +97,7 @@ def get_api_landing_page():
                 "title": "the API definition",
             },
             {
-                "path": "/MAAS/docs/api.html",
+                "path": "/MAAS/api/docs/",
                 "rel": "service-doc",
                 "type": "text/html",
                 "title": "the API documentation",
diff --git a/src/maasserver/api/tests/test_oapi.py b/src/maasserver/api/tests/test_oapi.py
index 8ea0e79..641726d 100644
--- a/src/maasserver/api/tests/test_oapi.py
+++ b/src/maasserver/api/tests/test_oapi.py
@@ -5,7 +5,12 @@ import json
 
 import yaml
 
-from maasserver.api.doc_oapi import _render_oapi_paths, endpoint, landing_page
+from maasserver.api.doc_oapi import (
+    _render_oapi_paths,
+    endpoint,
+    landing_page,
+    openapi_docs_context,
+)
 from maasserver.models.config import Config
 from maasserver.testing.factory import factory
 from maasserver.testing.testcase import MAASServerTestCase
@@ -53,6 +58,18 @@ class TestApiEndpoint(MAASServerTestCase):
         self.assertEqual(maasserver["description"], f"{maas_name} API")
 
 
+class TestOAPIDocs(MAASServerTestCase):
+    def test_docs_point_to_api(self):
+        request = factory.make_fake_request()
+        page = landing_page(request)
+        content = json.loads(page.content)
+        oapi_res = content["resources"][1]
+        context = openapi_docs_context(request)
+        self.assertEqual(
+            context["openapi_url"], f"http://localhost:5240{oapi_res['path']}"
+        )
+
+
 class TestOAPISpec(MAASServerTestCase):
     def setUp(self):
         self.oapi_types = ["boolean", "integer", "number", "object", "string"]
@@ -103,6 +120,5 @@ class TestOAPISpec(MAASServerTestCase):
                     yield (k, v)
 
         for k, v in _get_all_key_values(_render_oapi_paths()):
-            print(k, v)
             if k == "type":
                 self.assertIn(v, self.oapi_types)
diff --git a/src/maasserver/templates/openapi.html b/src/maasserver/templates/openapi.html
new file mode 100644
index 0000000..5381de5
--- /dev/null
+++ b/src/maasserver/templates/openapi.html
@@ -0,0 +1,67 @@
+{# HTML for static distribution bundle build #}
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>MAAS API</title>
+    <link href="/MAAS/r/static/css/main.05850fff.css" rel="stylesheet">
+    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
+    <style>
+      html * {
+        font-family: ubuntu !important;
+        font-weight: 300 !important;
+        line-height: 1.5rem;
+      }
+      h3 {
+        min-width: 100%;
+      }
+      p {
+        margin: 0 !important;
+        max-width: 100% !important;
+      }
+    </style>
+  </head>
+
+  <body>
+    <header class="p-navigation is-dark" style="background-color: {{ maas_colour }};">
+      <div class="p-navigation__row">
+        <div class="p-navigation__banner">
+          <div class="p-navigation__tagged-logo">
+            <a aria-label="Homepage" class="p-navigation__link" href="/MAAS/r/dashboard">
+              <div class="p-navigation__logo-tag">
+                <svg class="p-navigation__logo-icon" fill="#fff" viewBox="0 0 165.5 174.3" xmlns="http://www.w3.org/2000/svg">
+                  <ellipse cx="15.57" cy="111.46" rx="13.44" ry="13.3"></ellipse>
+                  <path d="M156.94 101.45H31.88a18.91 18.91 0 0 1 .27 19.55c-.09.16-.2.31-.29.46h125.08a6 6 0 0 0 6.06-5.96v-8.06a6 6 0 0 0-6-6Z"></path>
+                  <ellipse cx="15.62" cy="63.98" rx="13.44" ry="13.3"></ellipse>
+                  <path d="M156.94 53.77H31.79a18.94 18.94 0 0 1 .42 19.75l-.16.24h124.89a6 6 0 0 0 6.06-5.94v-8.06a6 6 0 0 0-6-6Z"></path>
+                  <ellipse cx="16.79" cy="16.5" rx="13.44" ry="13.3"></ellipse>
+                  <path d="M156.94 6.5H33.1a19.15 19.15 0 0 1 2.21 5.11A18.82 18.82 0 0 1 33.42 26l-.29.46h123.81a6 6 0 0 0 6.06-5.9V12.5a6 6 0 0 0-6-6Z"></path><ellipse cx="15.57" cy="158.94" rx="13.44" ry="13.3"></ellipse>
+                  <path d="M156.94 149H31.88a18.88 18.88 0 0 1 .27 19.5c-.09.16-.19.31-.29.46h125.08A6 6 0 0 0 163 163v-8.06a6 6 0 0 0-6-6Z"></path>
+                </svg>
+              </div>
+              <span class="p-navigation__logo-title">Canonical MAAS</span>
+            </a>
+          </div>
+        </div>
+        <div style="margin: auto; margin-right:0;">
+          <a aria-label="Homepage" class="p-navigation__link" href="/MAAS/api/">
+            <div class="p-navigation__logo-title">{{ maas_name }} MAAS: {{ maas_version }}</div>
+          </a>
+        </div>
+      </header>
+    <div id="swagger-ui" style="max-width: 90rem; margin: auto;"></div>
+    <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
+    <script>
+      window.onload = function() {
+        window.ui = SwaggerUIBundle({
+          url: "{{ openapi_url }}",
+          dom_id: '#swagger-ui',
+          deepLinking: true,
+          presets: [
+            SwaggerUIBundle.presets.apis,
+          ],
+        });
+      };
+    </script>
+  </body>
+</html>
\ No newline at end of file
diff --git a/src/maasserver/urls.py b/src/maasserver/urls.py
index c2cba09..63ef2ec 100644
--- a/src/maasserver/urls.py
+++ b/src/maasserver/urls.py
@@ -9,7 +9,7 @@ from django.urls import include, re_path
 from django.views.generic import TemplateView
 
 from maasserver import urls_api
-from maasserver.api.doc_oapi import landing_page
+from maasserver.api.doc_oapi import landing_page, openapi_docs_context
 from maasserver.bootresources import (
     simplestreams_file_handler,
     simplestreams_stream_handler,
@@ -78,6 +78,13 @@ urlpatterns += [re_path(r"^accounts/logout/$", logout, name="logout")]
 # API URLs. If old API requested, provide error message directing to new API.
 urlpatterns += [
     re_path(r"^api/$", landing_page),
+    re_path(
+        r"^api/docs/",
+        lambda request: TemplateView.as_view(
+            template_name="openapi.html",
+            extra_context=openapi_docs_context(request),
+        ),
+    ),
     re_path(r"^api/2\.0/", include(urls_api)),
     re_path(
         r"^api/version/",