1
diff --git a/.gitignore b/.gitignore
2
index d84ca68..31cd627 100644
3
--- a/.gitignore
4
+++ b/.gitignore
5
@@ -26,6 +26,7 @@
6
26
/develop-eggs
26
/develop-eggs
7
27
/dist
27
/dist
8
28
/api-docs.rst
28
/api-docs.rst
9
29
/openapi.yaml
10
29
/eggs
30
/eggs
11
30
/etc/maas/rackd.conf
31
/etc/maas/rackd.conf
12
31
/etc/maas/regiond.conf
32
/etc/maas/regiond.conf
13
diff --git a/Makefile b/Makefile
14
index cd8f092..5a5c2af 100644
15
--- a/Makefile
16
+++ b/Makefile
17
@@ -218,7 +218,10 @@ check: clean test
18
218
api-docs.rst: bin/maas-region src/maasserver/api/doc_handler.py syncdb
218
api-docs.rst: bin/maas-region src/maasserver/api/doc_handler.py syncdb
19
219
	bin/maas-region generate_api_doc > $@
219
	bin/maas-region generate_api_doc > $@
20
220
220
22
221
doc: api-docs.rst
221
openapi.yaml: bin/maas-region src/maasserver/api/doc_handler.py syncdb
23
222
	bin/maas-region generate_oapi_spec > $@
24
223
25
224
doc: api-docs.rst openapi.yaml
26
222
.PHONY: doc
225
.PHONY: doc
27
223
226
28
224
.run: run-skel
227
.run: run-skel
29
diff --git a/src/maasserver/api/doc_oapi.py b/src/maasserver/api/doc_oapi.py
30
index d747499..1676c57 100644
31
--- a/src/maasserver/api/doc_oapi.py
32
+++ b/src/maasserver/api/doc_oapi.py
33
@@ -19,35 +19,9 @@ from maasserver.api.annotations import APIDocstringParser
34
19
from maasserver.api.doc import find_api_resources, generate_doc
19
from maasserver.api.doc import find_api_resources, generate_doc
35
20
from maasserver.djangosettings import settings
20
from maasserver.djangosettings import settings
36
21
from maasserver.models.config import Config
21
from maasserver.models.config import Config
37
22
from maasserver.models.controllerinfo import get_maas_version
38
23
from maasserver.utils import build_absolute_uri
22
from maasserver.utils import build_absolute_uri
39
24
23
40
25
24
41
26
def openapi_docs_context(request):
42
27
    """Return the aadditional context needed for the oapi doc template to function"""
43
28
    colourmap = {
44
29
        "bark": "#585841",
45
30
        "blue": "#0060bf",
46
31
        "magenta": "#974097",
47
32
        "olive": "#3d5f11",
48
33
        "prussian green": "#225d5c",
49
34
        "purple": "#7764d8",
50
35
        "red": "#a71b33",
51
36
        "sage": "#4e5f51",
52
37
        "viridian": "#025a3d",
53
38
    }
54
39
    local_server = _get_maas_servers()[0]
55
40
    context = {
56
41
        "openapi_url": local_server["url"] + "openapi.yaml",
57
42
        "maas_colour": colourmap.get(
58
43
            Config.objects.get_config("theme").lower(), "#262626"
59
44
        ),
60
45
        "maas_name": local_server["description"].removesuffix(" API"),
61
46
        "maas_version": get_maas_version(),
62
47
    }
63
48
    return context
64
49
65
50
66
51
def landing_page(request):
25
def landing_page(request):
67
52
    """Render a landing page with pointers for the MAAS API.
26
    """Render a landing page with pointers for the MAAS API.
68
53
27
69
@@ -71,6 +45,7 @@ def endpoint(request):
70
71
        with the OpenApi spec 3.0.
45
        with the OpenApi spec 3.0.
71
72
    """
46
    """
72
73
    description = get_api_endpoint()
47
    description = get_api_endpoint()
73
48
    description["servers"] = _get_maas_servers()
74
74
    # Return as a YAML document
49
    # Return as a YAML document
75
75
    return HttpResponse(
50
    return HttpResponse(
76
76
        yaml.dump(description),
51
        yaml.dump(description),
77
@@ -125,7 +100,6 @@ def get_api_endpoint():
78
125
            "description": "MAAS API documentation",
100
            "description": "MAAS API documentation",
79
126
            "url": "/MAAS/docs/api.html",
101
            "url": "/MAAS/docs/api.html",
80
127
        },
102
        },
81
128
        "servers": _get_maas_servers(),
82
129
    }
103
    }
83
130
    return description
104
    return description
84
131
105
85
diff --git a/src/maasserver/api/tests/test_oapi.py b/src/maasserver/api/tests/test_oapi.py
86
index 641726d..0e27da9 100644
87
--- a/src/maasserver/api/tests/test_oapi.py
88
+++ b/src/maasserver/api/tests/test_oapi.py
89
@@ -5,12 +5,7 @@ import json
90
5
5
91
6
import yaml
6
import yaml
92
7
7
99
8
from maasserver.api.doc_oapi import (
8
from maasserver.api.doc_oapi import _render_oapi_paths, endpoint, landing_page
94
9
    _render_oapi_paths,
95
10
    endpoint,
96
11
    landing_page,
97
12
    openapi_docs_context,
98
13
)
100
14
from maasserver.models.config import Config
9
from maasserver.models.config import Config
101
15
from maasserver.testing.factory import factory
10
from maasserver.testing.factory import factory
102
16
from maasserver.testing.testcase import MAASServerTestCase
11
from maasserver.testing.testcase import MAASServerTestCase
103
@@ -58,18 +53,6 @@ class TestApiEndpoint(MAASServerTestCase):
104
58
        self.assertEqual(maasserver["description"], f"{maas_name} API")
53
        self.assertEqual(maasserver["description"], f"{maas_name} API")
105
59
54
106
60
55
107
61
class TestOAPIDocs(MAASServerTestCase):
108
62
    def test_docs_point_to_api(self):
109
63
        request = factory.make_fake_request()
110
64
        page = landing_page(request)
111
65
        content = json.loads(page.content)
112
66
        oapi_res = content["resources"][1]
113
67
        context = openapi_docs_context(request)
114
68
        self.assertEqual(
115
69
            context["openapi_url"], f"http://localhost:5240{oapi_res['path']}"
116
70
        )
117
71
118
72
119
73
class TestOAPISpec(MAASServerTestCase):
56
class TestOAPISpec(MAASServerTestCase):
120
74
    def setUp(self):
57
    def setUp(self):
121
75
        self.oapi_types = ["boolean", "integer", "number", "object", "string"]
58
        self.oapi_types = ["boolean", "integer", "number", "object", "string"]
122
diff --git a/src/maasserver/management/commands/generate_oapi_spec.py b/src/maasserver/management/commands/generate_oapi_spec.py
123
76
new file mode 100644
59
new file mode 100644
124
index 0000000..5299fcc
125
--- /dev/null
126
+++ b/src/maasserver/management/commands/generate_oapi_spec.py
127
@@ -0,0 +1,17 @@
128
1
# Copyright 2022 Canonical Ltd.  This software is licensed under the
129
2
# GNU Affero General Public License version 3 (see the file LICENSE).
130
3
131
4
"""Django command: generate the Open API specification."""
132
5
133
6
134
7
from django.core.management.base import BaseCommand
135
8
import yaml
136
9
137
10
from maasserver.api.doc_oapi import get_api_endpoint
138
11
139
12
140
13
class Command(BaseCommand):
141
14
    def handle(self, *args, **options):
142
15
        oapi = get_api_endpoint()
143
16
        oapi["externalDocs"]["url"] = "https://maas.io/docs"
144
17
        yaml.dump(oapi, self.stdout)
145
diff --git a/src/maasserver/templates/openapi.html b/src/maasserver/templates/openapi.html
146
index 5381de5..41c492b 100644
147
--- a/src/maasserver/templates/openapi.html
148
+++ b/src/maasserver/templates/openapi.html
149
@@ -4,8 +4,8 @@
150
4
  <head>
4
  <head>
151
5
    <meta charset="UTF-8">
5
    <meta charset="UTF-8">
152
6
    <title>MAAS API</title>
6
    <title>MAAS API</title>
155
7
    <link href="/MAAS/r/static/css/main.05850fff.css" rel="stylesheet">
7
    <link href="https://maas.io/static/css/main.css" rel="stylesheet">
156
8
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui.css" />
8
    <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@latest/swagger-ui.css" />
157
9
    <style>
9
    <style>
158
10
      html * {
10
      html * {
159
11
        font-family: ubuntu !important;
11
        font-family: ubuntu !important;
160
@@ -23,7 +23,7 @@
161
23
  </head>
23
  </head>
162
24
24
163
25
  <body>
25
  <body>
165
26
    <header class="p-navigation is-dark" style="background-color: {{ maas_colour }};">
26
    <header class="p-navigation is-dark" style="background-color: #262626;">
166
27
      <div class="p-navigation__row">
27
      <div class="p-navigation__row">
167
28
        <div class="p-navigation__banner">
28
        <div class="p-navigation__banner">
168
29
          <div class="p-navigation__tagged-logo">
29
          <div class="p-navigation__tagged-logo">
169
@@ -45,16 +45,16 @@
170
45
        </div>
45
        </div>
171
46
        <div style="margin: auto; margin-right:0;">
46
        <div style="margin: auto; margin-right:0;">
172
47
          <a aria-label="Homepage" class="p-navigation__link" href="/MAAS/api/">
47
          <a aria-label="Homepage" class="p-navigation__link" href="/MAAS/api/">
174
48
            <div class="p-navigation__logo-title">{{ maas_name }} MAAS: {{ maas_version }}</div>
48
            <div class="p-navigation__logo-title">MAAS</div>
175
49
          </a>
49
          </a>
176
50
        </div>
50
        </div>
177
51
      </header>
51
      </header>
180
52
    <div id="swagger-ui" style="max-width: 90rem; margin: auto;"></div>
52
    <div id="swagger-ui" style="max-width: 72rem; margin: auto;"></div>
181
53
    <script src="https://unpkg.com/swagger-ui-dist@4.5.0/swagger-ui-bundle.js" crossorigin></script>
53
    <script src="https://unpkg.com/swagger-ui-dist@latest/swagger-ui-bundle.js" crossorigin></script>
182
54
    <script>
54
    <script>
183
55
      window.onload = function() {
55
      window.onload = function() {
184
56
        window.ui = SwaggerUIBundle({
56
        window.ui = SwaggerUIBundle({
186
57
          url: "{{ openapi_url }}",
57
          url: "/MAAS/api/2.0/openapi.yaml",
187
58
          dom_id: '#swagger-ui',
58
          dom_id: '#swagger-ui',
188
59
          deepLinking: true,
59
          deepLinking: true,
189
60
          presets: [
60
          presets: [
190
diff --git a/src/maasserver/urls.py b/src/maasserver/urls.py
191
index 63ef2ec..2f3169c 100644
192
--- a/src/maasserver/urls.py
193
+++ b/src/maasserver/urls.py
194
@@ -9,7 +9,7 @@ from django.urls import include, re_path
195
9
from django.views.generic import TemplateView
9
from django.views.generic import TemplateView
196
10
10
197
11
from maasserver import urls_api
11
from maasserver import urls_api
199
12
from maasserver.api.doc_oapi import landing_page, openapi_docs_context
12
from maasserver.api.doc_oapi import landing_page
200
13
from maasserver.bootresources import (
13
from maasserver.bootresources import (
201
14
    simplestreams_file_handler,
14
    simplestreams_file_handler,
202
15
    simplestreams_stream_handler,
15
    simplestreams_stream_handler,
203
@@ -78,13 +78,7 @@ urlpatterns += [re_path(r"^accounts/logout/$", logout, name="logout")]
204
78
# API URLs. If old API requested, provide error message directing to new API.
78
# API URLs. If old API requested, provide error message directing to new API.
205
79
urlpatterns += [
79
urlpatterns += [
206
80
    re_path(r"^api/$", landing_page),
80
    re_path(r"^api/$", landing_page),
214
81
    re_path(
81
    re_path(r"^api/docs/", TemplateView.as_view(template_name="openapi.html")),
208
82
        r"^api/docs/",
209
83
        lambda request: TemplateView.as_view(
210
84
            template_name="openapi.html",
211
85
            extra_context=openapi_docs_context(request),
212
86
        ),
213
87
    ),
215
88
    re_path(r"^api/2\.0/", include(urls_api)),
82
    re_path(r"^api/2\.0/", include(urls_api)),
216
89
    re_path(
83
    re_path(
217
90
        r"^api/version/",
84
        r"^api/version/",
Status:	Merged
Approved by:	Jack Lloyd-Walters on 2022-08-18
Approved revision:	2800e6eef6cddee649e2ca135c4c9b5a03ab30d7
Merge reported by:	MAAS Lander
Merged at revision:	not available
Proposed branch:	~lloydwaltersj/maas:fix-oapi-docs
Merge into:	maas:master
Diff against target:	217 lines (+33/-61) 7 files modified .gitignore (+1/-0) Makefile (+4/-1) src/maasserver/api/doc_oapi.py (+1/-27) src/maasserver/api/tests/test_oapi.py (+1/-18) src/maasserver/management/commands/generate_oapi_spec.py (+17/-0) src/maasserver/templates/openapi.html (+7/-7) src/maasserver/urls.py (+2/-8)
Related bugs:	Link a bug report
Reviewer	Date Requested	Status
MAAS Lander		Approve on 2022-08-17
Adam Collard (community)		Approve on 2022-08-17
Alexsander de Souza	2022-08-05	Approve on 2022-08-15
Review via email: mp+427900@code.launchpad.net