Merge ~lloydwaltersj/maas:missing-response into maas:master

[Jack Lloyd-Walters]

Generate responses for API operations.

OAS3 requires all operations present some responses, but some of our API operations do not have any defined.

[Adam Collard (adam-collard)]

Merge conflicts

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

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

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/393/consoleText
COMMIT: 0e830a1cb0d1a7b637989c105f362e23a4b6cd9f

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/394/consoleText
COMMIT: 372c110118966ff2981eb988d4d157bcd6cc7f58

review: Needs Fixing

[Jack Lloyd-Walters (lloydwaltersj)]

jenkins: !test

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/395/consoleText
COMMIT: 372c110118966ff2981eb988d4d157bcd6cc7f58

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 7c9ee43b86e273e5afb69d7a2ef393c45046240b

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 7c628c8d3c411717abc060aa6d132d70809fe3df

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: f17159fcb1e073fbb494540e1bc1d474dce50334

review: Approve

[Adam Collard (adam-collard)]

Let's clean this up with the @deprecated work but get it landed for now

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

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

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: e9f2306ed4468566f6e56ecebbf9275efe186801

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED
LOG: http://maas-ci.internal:8080/job/maas-tester/473/consoleText
COMMIT: 42977b1868fab13ba490ae0f35424c47134d11c5

review: Needs Fixing

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: b8594841bc15b78be23b6b429d8ef8e744662172

review: Approve

[MAAS Lander (maas-lander)]

UNIT TESTS
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: SUCCESS
COMMIT: 54c3fcc4efc1ea4d29f205f379f2b86752ec93d6

review: Approve

[MAAS Lander (maas-lander)]

LANDING
-b missing-response lp:~lloydwaltersj/maas/+git/maas into -b master lp:~maas-committers/maas

STATUS: FAILED BUILD
LOG: http://maas-ci.internal:8080/job/maas-tester/483/consoleText

diff --git a/src/maasserver/api/doc_oapi.py b/src/maasserver/api/doc_oapi.py
index 25922cd..c0d0212 100644
--- a/src/maasserver/api/doc_oapi.py
+++ b/src/maasserver/api/doc_oapi.py
@@ -7,7 +7,7 @@ This definition follows the rules and limitations of the ReST documentation.
 (see doc.py and doc_handler.py).
 """
 
-from inspect import getdoc
+from inspect import getdoc, signature
 import json
 import re
 from textwrap import dedent
@@ -144,7 +144,9 @@ def _prettify(doc):
     return re.sub("(?<![.\n])[\n]+", " ", dedent(doc)).strip()
 
 
-def _render_oapi_oper_item(http_method, op, doc, uri_params, function):
+def _render_oapi_oper_item(
+    http_method, op, doc, uri_params, function, resources
+):
     oper_id = op or support.OperationsResource.crudmap.get(http_method)
     oper_obj = {
         "operationId": f"{doc.name}_{oper_id}",
@@ -154,14 +156,16 @@ def _render_oapi_oper_item(http_method, op, doc, uri_params, function):
         "responses": {},
     }
     oper_docstring = _oapi_item_from_docstring(
-        function, http_method, uri_params
+        function, http_method, uri_params, doc, resources
     )
     # Only overwrite the values that are non-blank
     oper_obj.update({k: v for k, v in oper_docstring.items() if v})
     return oper_obj
 
 
-def _oapi_item_from_docstring(function, http_method, uri_params):
+def _oapi_item_from_docstring(
+    function, http_method, uri_params, doc, resources
+):
     def _type_to_string(schema):
         match schema:
             case "Boolean":
@@ -187,6 +191,9 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
                 paired.extend([status, content])
             else:
                 content = response
+        # edge case where a response is not given in the docstring
+        if paired == [] and content:
+            paired.extend([content, content])
         paired = iter(paired)
         return zip(paired, paired)
 
@@ -202,6 +209,8 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
         ap_dict = ap.get_dict()
         oper_obj["summary"] = ap_dict["description_title"].strip()
         oper_obj["description"] = _prettify(ap_dict["description"])
+        if "deprecated" in oper_obj["description"].lower():
+            oper_obj["deprecated"] = True
         for param in ap_dict["params"]:
             description = _prettify(param["description_stripped"])
             name = param["name"].strip("}{")
@@ -268,11 +277,38 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
 
             status_code = status["name"]
             if not status_code.isdigit():
-                status_code = _prettify(status["description_stripped"])
+                status_code = (
+                    "200" if "success" in status_code.lower() else "404"
+                )
             oper_obj.setdefault("responses", {}).update(
                 {status_code: response},
             )
 
+    # populate deprecated functions properties using their replacement
+    if (
+        replacement_method := getattr(function, "deprecated", function)
+    ) is not function:
+        oper_obj["deprecated"] = True
+        oper_obj["responses"] = _oapi_item_from_docstring(
+            replacement_method, http_method, uri_params, doc, resources
+        )["responses"]
+
+    # if a response is still empty, query the function
+    if not oper_obj.get("responses"):
+        # fetch a response by calling the function
+        status, msg = "200", ""
+        try:
+            msg = function(*[""] * len(signature(function).parameters))
+        except Exception as e:
+            status = "404"
+            msg = str(e)
+        oper_obj["responses"] = {
+            status: {
+                "content": {"text/plain": {"schema": {"type": "string"}}},
+                "description": msg,
+            }
+        }
+
     if body.get("properties"):
         oper_obj.update(
             {
@@ -317,6 +353,6 @@ def _render_oapi_paths():
                 _new_path_item(params),
             )
             path_item[http_method.lower()] = _render_oapi_oper_item(
-                http_method, op, doc, params, function
+                http_method, op, doc, params, function, resources
             )
     return paths
diff --git a/src/maasserver/api/machines.py b/src/maasserver/api/machines.py
index b6e92c6..93175c4 100644
--- a/src/maasserver/api/machines.py
+++ b/src/maasserver/api/machines.py
@@ -669,6 +669,21 @@ class MachineHandler(NodeHandler, WorkloadAnnotationsMixin, PowerMixin):
 
     @operation(idempotent=True)
     def get_token(self, request, system_id):
+        """@description-title Get a machine token
+
+        @param (string) "{system_id}" [required=true] The machines' system_id.
+
+        @success (http-status-code) "200" 200
+        @success (json) "success-json" A JSON object containing information
+        about the machine token.
+        @success-example "success-json" [exkey=machines-placeholder]
+        placeholder text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine is not found.
+        @error-example "not-found"
+            No Machine matches the given query.
+        """
         node = self.model.objects.get_node_or_404(
             system_id=system_id,
             user=request.user,
diff --git a/src/maasserver/management/commands/tests/test_generate_oapi.py b/src/maasserver/management/commands/tests/test_generate_oapi.py
index 2c49814..1431de1 100644
--- a/src/maasserver/management/commands/tests/test_generate_oapi.py
+++ b/src/maasserver/management/commands/tests/test_generate_oapi.py
@@ -10,10 +10,10 @@ from django.core.management import call_command
 import yaml
 
 from maasserver.api.doc_oapi import get_api_endpoint
-from maastesting.testcase import MAASTestCase
+from maasserver.testing.testcase import MAASServerTestCase
 
 
-class TestOAPIDoc(MAASTestCase):
+class TestOAPIDoc(MAASServerTestCase):
     def test_generate_spec(self):
         spec = get_api_endpoint()
         spec["externalDocs"]["url"] = "https://maas.io/docs"