Merge ~lloydwaltersj/maas:OpenApi-Endpoint into maas:master

[Jack Lloyd-Walters]

Introduce OpenApi endpoint

[MAAS Lander (maas-lander)]

UNIT TESTS
-b OpenApi-Endpoint lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 631a5f07824410fb6559865300372e3afafca5b4

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b OpenApi-Endpoint lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

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

review: Needs Fixing

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

[Alberto Donato (ack)]

looks mostly good, a couple of comments and a question inline

review: Needs Information

[MAAS Lander (maas-lander)]

UNIT TESTS
-b OpenApi-Endpoint lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: ddbc67b4b5e16c7408cc72ee869fde0d960e0637

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b OpenApi-Endpoint lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: d0852abe819e5dee8afd4c08f97a508e4dd9998c

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b OpenApi-Endpoint lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 4d1c04bdada5c8991272fd402eca18f7d7138f72

review: Approve

[Alexsander de Souza (alexsander-souza)]

let's move OpenAPI-specific functions to `doc_oapi.py`, keeping the ReST and the OpenAPI segregated

[MAAS Lander (maas-lander)]

UNIT TESTS
-b OpenApi-Endpoint lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 82c175c5d16198d7bc5d36755ccd6cc1b2ed3284

review: Approve

[Adam Collard (adam-collard)]

+1 with a question inline

review: Approve

diff --git a/src/maasserver/api/doc.py b/src/maasserver/api/doc.py
index 4e5c3d4..6bc7ae2 100644
--- a/src/maasserver/api/doc.py
+++ b/src/maasserver/api/doc.py
@@ -36,35 +36,6 @@ def get_api_description():
     return description
 
 
-def get_api_landing_page():
-    """Return the API landing page"""
-    description = {
-        "title": "MAAS API",
-        "description": "API landing page for MAAS",
-        "resources": [
-            {
-                "path": "/MAAS/api",
-                "rel": "self",
-                "type": "application/json",
-                "title": "this document",
-            },
-            {
-                "path": "/MAAS/api/2.0/openapi.yaml",
-                "rel": "service-desc",
-                "type": "application/openapi+yaml",
-                "title": "the API definition",
-            },
-            {
-                "path": "/MAAS/docs/api.html",
-                "rel": "service-doc",
-                "type": "text/html",
-                "title": "the API documentation",
-            },
-        ],
-    }
-    return description
-
-
 def find_api_resources(urlconf=None):
     """Find the API resources defined in `urlconf`.
 
diff --git a/src/maasserver/api/doc_handler.py b/src/maasserver/api/doc_handler.py
index f8e5ba8..3dd41c6 100644
--- a/src/maasserver/api/doc_handler.py
+++ b/src/maasserver/api/doc_handler.py
@@ -71,7 +71,6 @@ from maasserver.api.doc import (
     generate_pod_types_doc,
     generate_power_types_doc,
     get_api_description,
-    get_api_landing_page,
 )
 from maasserver.api.templates import APITemplateRenderer
 from maasserver.utils import build_absolute_uri
@@ -243,19 +242,3 @@ def describe(request):
         json.dumps(description, sort_keys=True),
         content_type="application/json",
     )
-
-
-def api_landing_page(request):
-    """Render a landing page with pointers for the MAAS API.
-
-    :return: An `HttpResponse` containing a JSON page with pointers to both
-        human-readable documentation and api definitions.
-    """
-    description = get_api_landing_page()
-    for link in description["resources"]:
-        link["href"] = build_absolute_uri(request, link["path"])
-    # Return as a JSON document
-    return HttpResponse(
-        json.dumps(description),
-        content_type="application/json",
-    )
diff --git a/src/maasserver/api/doc_oapi.py b/src/maasserver/api/doc_oapi.py
new file mode 100644
index 0000000..d9dfe25
--- /dev/null
+++ b/src/maasserver/api/doc_oapi.py
@@ -0,0 +1,84 @@
+# Copyright 2014-2022 Canonical Ltd.  This software is licensed under the
+# GNU Affero General Public License version 3 (see the file LICENSE).
+
+import json
+
+from django.http import HttpResponse
+import yaml
+
+from maasserver.utils import build_absolute_uri
+
+
+def landing_page(request):
+    """Render a landing page with pointers for the MAAS API.
+
+    :return: An `HttpResponse` containing a JSON page with pointers to both
+        human-readable documentation and api definitions.
+    """
+    description = get_api_landing_page()
+    for link in description["resources"]:
+        link["href"] = build_absolute_uri(request, link["path"])
+    # Return as a JSON document
+    return HttpResponse(
+        json.dumps(description),
+        content_type="application/json",
+    )
+
+
+def endpoint(request):
+    """Render the OpenApi endpoint.
+
+    :return: An `HttpResponse` containing a YAML document that complies
+        with the OpenApi spec 3.0.
+    """
+    description = get_api_endpoint()
+    doc = description["externalDocs"]
+    doc["url"] = build_absolute_uri(request, doc["url"])
+    # Return as a YAML document
+    return HttpResponse(
+        yaml.dump(description),
+        content_type="application/yaml",
+    )
+
+
+def get_api_landing_page():
+    """Return the API landing page"""
+    description = {
+        "title": "MAAS API",
+        "description": "API landing page for MAAS",
+        "resources": [
+            {
+                "path": "/MAAS/api",
+                "rel": "self",
+                "type": "application/json",
+                "title": "this document",
+            },
+            {
+                "path": "/MAAS/api/2.0/openapi.yaml",
+                "rel": "service-desc",
+                "type": "application/openapi+yaml",
+                "title": "the API definition",
+            },
+            {
+                "path": "/MAAS/docs/api.html",
+                "rel": "service-doc",
+                "type": "text/html",
+                "title": "the API documentation",
+            },
+        ],
+    }
+    return description
+
+
+def get_api_endpoint():
+    """Return the API endpoint"""
+    description = {
+        "openapi": "3.0.0",
+        "info": {"title": "MAAS OpenApi Endpoint", "version": "1.0.0"},
+        "paths": [],
+        "externalDocs": {
+            "description": "MAAS API documentation",
+            "url": "/MAAS/docs/api.html",
+        },
+    }
+    return description
diff --git a/src/maasserver/api/tests/test_doc.py b/src/maasserver/api/tests/test_doc.py
index cb9d061..ad02930 100644
--- a/src/maasserver/api/tests/test_doc.py
+++ b/src/maasserver/api/tests/test_doc.py
@@ -26,6 +26,7 @@ from testtools.matchers import (
     MatchesStructure,
     Not,
 )
+import yaml
 
 from maasserver.api import doc as doc_module
 from maasserver.api.doc import (
@@ -41,7 +42,8 @@ from maasserver.api.doc import (
     generate_power_types_doc,
     get_api_description,
 )
-from maasserver.api.doc_handler import api_landing_page, render_api_docs
+from maasserver.api.doc_handler import render_api_docs
+from maasserver.api.doc_oapi import endpoint, landing_page
 from maasserver.api.support import (
     operation,
     OperationsHandler,
@@ -83,14 +85,28 @@ class TestGetAPIDescription(MAASTestCase):
 class TestLandingPage(MAASTestCase):
     def test_links(self):
         request = factory.make_fake_request()
-        landing_page = api_landing_page(request)
-        content = json.loads(landing_page.content)
+        page = landing_page(request)
+        content = json.loads(page.content)
         resources = content["resources"]
         host = request.get_host()
         for link in resources:
             href = f"http://{host}{link['path']}"
             self.assertEqual(link["href"], href)
-        self.assertEqual(resources[0]["type"], landing_page["content-type"])
+        self.assertEqual(resources[0]["type"], page["content-type"])
+
+
+class TestApiEndpoint(MAASTestCase):
+    def test_required_fields(self):
+        request = factory.make_fake_request()
+        page = endpoint(request)
+        content = yaml.safe_load(page.content)
+        self.assertIn("openapi", content)
+        self.assertIn("info", content)
+        self.assertIn("paths", content)
+        info = content["info"]
+        self.assertIsInstance(info, dict)
+        self.assertIn("title", info)
+        self.assertIn("version", info)
 
 
 class TestFindingResources(MAASTestCase):
diff --git a/src/maasserver/urls.py b/src/maasserver/urls.py
index 404dc11..c2cba09 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_handler import api_landing_page
+from maasserver.api.doc_oapi import landing_page
 from maasserver.bootresources import (
     simplestreams_file_handler,
     simplestreams_stream_handler,
@@ -77,7 +77,7 @@ 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/$", api_landing_page),
+    re_path(r"^api/$", landing_page),
     re_path(r"^api/2\.0/", include(urls_api)),
     re_path(
         r"^api/version/",
diff --git a/src/maasserver/urls_api.py b/src/maasserver/urls_api.py
index bd7eb41..184263b 100644
--- a/src/maasserver/urls_api.py
+++ b/src/maasserver/urls_api.py
@@ -37,6 +37,7 @@ from maasserver.api.dnsresourcerecords import (
 )
 from maasserver.api.dnsresources import DNSResourceHandler, DNSResourcesHandler
 from maasserver.api.doc_handler import describe
+from maasserver.api.doc_oapi import endpoint
 from maasserver.api.domains import DomainHandler, DomainsHandler
 from maasserver.api.events import EventsHandler
 from maasserver.api.fabrics import FabricHandler, FabricsHandler
@@ -330,11 +331,11 @@ license_keys_handler = AdminRestrictedResource(
     LicenseKeysHandler, authentication=api_auth
 )
 
-
 # API URLs accessible to anonymous users.
 urlpatterns = [
     re_path(r"describe/$", describe, name="describe"),
     re_path(r"version/$", version_handler, name="version_handler"),
+    re_path(r"openapi.yaml$", endpoint, name="openapi_endpoint"),
 ]