1
diff --git a/src/maasserver/api/doc_oapi.py b/src/maasserver/api/doc_oapi.py
2
index 543c571..c579acd 100644
3
--- a/src/maasserver/api/doc_oapi.py
4
+++ b/src/maasserver/api/doc_oapi.py
5
@@ -9,6 +9,7 @@ This definition follows the rules and limitations of the ReST documentation.
6
9
9
7
10
from inspect import getdoc
10
from inspect import getdoc
8
11
import json
11
import json
9
12
import re
10
12
from textwrap import dedent
13
from textwrap import dedent
11
13
14
12
14
from django.http import HttpResponse
15
from django.http import HttpResponse
13
@@ -135,13 +136,21 @@ def _new_path_item(params):
14
135
    return path_item
136
    return path_item
15
136
137
16
137
138
17
139
def _prettify(doc):
18
140
    """Cleans up text by replacing newlines with spaces, so that sentences are
19
141
    not broken apart prematurely.
20
142
    Respects paragraphing by not replacing newlines that occur after periods.
21
143
    """
22
144
    return re.sub("(?<![.\n])[\n]+", " ", dedent(doc)).strip()
23
145
24
146
25
138
def _render_oapi_oper_item(http_method, op, doc, uri_params, function):
147
def _render_oapi_oper_item(http_method, op, doc, uri_params, function):
26
139
    oper_id = op or support.OperationsResource.crudmap.get(http_method)
148
    oper_id = op or support.OperationsResource.crudmap.get(http_method)
27
140
    oper_obj = {
149
    oper_obj = {
28
141
        "operationId": f"{doc.name}_{oper_id}",
150
        "operationId": f"{doc.name}_{oper_id}",
29
142
        "tags": [doc.handler.api_doc_section_name],
151
        "tags": [doc.handler.api_doc_section_name],
30
143
        "summary": f"{doc.name} {oper_id}",
152
        "summary": f"{doc.name} {oper_id}",
32
144
        "description": dedent(doc.doc).strip(),
153
        "description": _prettify(doc.doc),
33
145
        "responses": {},
154
        "responses": {},
34
146
    }
155
    }
35
147
    oper_docstring = _oapi_item_from_docstring(
156
    oper_docstring = _oapi_item_from_docstring(
36
@@ -192,9 +201,9 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
37
192
        ap.parse(docstring)
201
        ap.parse(docstring)
38
193
        ap_dict = ap.get_dict()
202
        ap_dict = ap.get_dict()
39
194
        oper_obj["summary"] = ap_dict["description_title"].strip()
203
        oper_obj["summary"] = ap_dict["description_title"].strip()
41
195
        oper_obj["description"] = ap_dict["description"].strip()
204
        oper_obj["description"] = _prettify(ap_dict["description"])
42
196
        for param in ap_dict["params"]:
205
        for param in ap_dict["params"]:
44
197
            description = param["description_stripped"]
206
            description = _prettify(param["description_stripped"])
45
198
            name = param["name"].strip("}{")
207
            name = param["name"].strip("}{")
46
199
            required = param["options"]["required"].lower() == "true"
208
            required = param["options"]["required"].lower() == "true"
47
200
            if param["name"][0] == "{":
209
            if param["name"][0] == "{":
48
@@ -222,8 +231,10 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
49
222
231
50
223
        for (status, content) in _response_pair(ap_dict):
232
        for (status, content) in _response_pair(ap_dict):
51
224
            response = {
233
            response = {
54
225
                "description": content.get(
234
                "description": _prettify(
55
226
                    "description_stripped", status["description_stripped"]
235
                    content.get(
56
236
                        "description_stripped", status["description_stripped"]
57
237
                    )
58
227
                ),
238
                ),
59
228
            }
239
            }
60
229
            match content.get("type", "").lower():
240
            match content.get("type", "").lower():
61
@@ -254,7 +265,7 @@ def _oapi_item_from_docstring(function, http_method, uri_params):
62
254
265
63
255
            status_code = status["name"]
266
            status_code = status["name"]
64
256
            if not status_code.isdigit():
267
            if not status_code.isdigit():
66
257
                status_code = status["description_stripped"]
268
                status_code = _prettify(status["description_stripped"])
67
258
            oper_obj.setdefault("responses", {}).update(
269
            oper_obj.setdefault("responses", {}).update(
68
259
                {status_code: response},
270
                {status_code: response},
69
260
            )
271
            )
70
diff --git a/src/maasserver/api/tests/test_oapi.py b/src/maasserver/api/tests/test_oapi.py
71
index 0e27da9..d22c2cc 100644
72
--- a/src/maasserver/api/tests/test_oapi.py
73
+++ b/src/maasserver/api/tests/test_oapi.py
74
@@ -5,7 +5,12 @@ import json
75
5
5
76
6
import yaml
6
import yaml
77
7
7
79
8
from maasserver.api.doc_oapi import _render_oapi_paths, endpoint, landing_page
8
from maasserver.api.doc_oapi import (
80
9
    _prettify,
81
10
    _render_oapi_paths,
82
11
    endpoint,
83
12
    landing_page,
84
13
)
85
9
from maasserver.models.config import Config
14
from maasserver.models.config import Config
86
10
from maasserver.testing.factory import factory
15
from maasserver.testing.factory import factory
87
11
from maasserver.testing.testcase import MAASServerTestCase
16
from maasserver.testing.testcase import MAASServerTestCase
88
@@ -105,3 +110,40 @@ class TestOAPISpec(MAASServerTestCase):
89
105
        for k, v in _get_all_key_values(_render_oapi_paths()):
110
        for k, v in _get_all_key_values(_render_oapi_paths()):
90
106
            if k == "type":
111
            if k == "type":
91
107
                self.assertIn(v, self.oapi_types)
112
                self.assertIn(v, self.oapi_types)
92
113
93
114
94
115
class TestPrettify(MAASTestCase):
95
116
    maxDiff = None
96
117
97
118
    def test_cleans_newlines(self):
98
119
        before = """\
99
120
Returns system details -- for example, LLDP and
100
121
101
122
``lshw`` XML dumps.
102
123
103
124
104
125
Returns a ``{detail_type: xml, ...}`` map, where
105
126
106
127
``detail_type`` is something like "lldp" or "lshw".
107
128
108
129
109
130
Note that this is returned as BSON and not JSON. This is for
110
131
111
132
efficiency, but mainly because JSON can''t do binary content without
112
133
113
134
applying additional encoding like base-64. The example output below is
114
135
115
136
represented in ASCII using ``bsondump example.bson`` and is for
116
137
117
138
demonstrative purposes."""
118
139
119
140
        after = """\
120
141
Returns system details -- for example, LLDP and ``lshw`` XML dumps.
121
142
122
143
123
144
Returns a ``{detail_type: xml, ...}`` map, where ``detail_type`` is something like "lldp" or "lshw".
124
145
125
146
126
147
Note that this is returned as BSON and not JSON. This is for efficiency, but mainly because JSON can''t do binary content without applying additional encoding like base-64. The example output below is represented in ASCII using ``bsondump example.bson`` and is for demonstrative purposes."""
127
148
128
149
        self.assertEqual(_prettify(before), after)
Status:	Merged
Approved by:	Jack Lloyd-Walters on 2022-08-24
Approved revision:	3b18ced2992ada2ea068ca3c84345b197ec6c6e4
Merge reported by:	MAAS Lander
Merged at revision:	not available
Proposed branch:	~lloydwaltersj/maas:oapi-line-break-op-desc
Merge into:	maas:master
Diff against target:	128 lines (+60/-7) 2 files modified src/maasserver/api/doc_oapi.py (+17/-6) src/maasserver/api/tests/test_oapi.py (+43/-1)
Related bugs:	Link a bug report
Reviewer	Date Requested	Status
MAAS Lander		Approve on 2022-08-24
Adam Collard (community)	2022-08-22	Approve on 2022-08-24
Review via email: mp+428727@code.launchpad.net