feat: add /openapi (OAS schema) and schema docs

This will make the REST API self describing
savannahghi · Nov 9, 2021 · 138d6c0 · 138d6c0
1 parent 686bbf0
commit 138d6c0
Show file tree

Hide file tree

Showing 4 changed files with 92 additions and 4 deletions.
diff --git a/config/settings/base.py b/config/settings/base.py
@@ -330,6 +330,7 @@
     "DATETIME_FORMAT": "iso-8601",
     "DATE_FORMAT": "iso-8601",
     "TIME_FORMAT": "iso-8601",
+    "UNICODE_JSON": "true",
 }
 
 # OAuth
@@ -354,7 +355,8 @@
 CORS_URLS_REGEX = r"^/api/.*$"
 
 # wagtail CMS
-WAGTAIL_SITE_NAME = "myCareHub"
+SITE_NAME = "myCareHub"
+WAGTAIL_SITE_NAME = SITE_NAME
 WAGTAIL_APPEND_SLASH = True
 WAGTAILSEARCH_HITS_MAX_AGE = 30
 WAGTAIL_I18N_ENABLED = True
@@ -403,3 +405,4 @@
 )
 
 GRAPHENE = {"SCHEMA": "mycarehub.schema.schema.schema"}
+API_VERSION = "0.0.1"
diff --git a/config/urls.py b/config/urls.py
@@ -6,9 +6,10 @@
 from django.urls import include, path, re_path
 from django.views import defaults as default_views
 from django.views.decorators.csrf import csrf_exempt
-from django.views.generic import RedirectView
+from django.views.generic import RedirectView, TemplateView
 from graphene_django.views import GraphQLView
 from rest_framework.authtoken.views import obtain_auth_token
+from rest_framework.schemas import get_schema_view
 from wagtail.admin import urls as wagtailadmin_urls
 from wagtail.core import urls as wagtail_urls
 from wagtail.documents import urls as wagtaildocs_urls
@@ -45,7 +46,7 @@
     # re_path(r"authoring", include("mycarehub.content.urls")),
     # For anything not caught by a more specific rule above, hand over to
     # Wagtail's serving mechanism
-    re_path(r"content", include(wagtail_urls)),
+    re_path(r"content", include(wagtail_urls), name="wagtail"),
     path("graphql", csrf_exempt(GraphQLView.as_view(graphiql=True)), name="graphql"),
     # content management
     path("admin/", include(wagtailadmin_urls)),
@@ -61,14 +62,43 @@
     urlpatterns += staticfiles_urlpatterns()
 
 # API URLS
-urlpatterns += [
+api_patterns = [
     # API base url
     path("api/", include("config.api_router")),
     # DRF auth token
     path("auth-token/", obtain_auth_token),
     # OAuth 2
     path("o/", include("oauth2_provider.urls", namespace="oauth2_provider")),
 ]
+urlpatterns += api_patterns
+
+# Open API Schema and automatic API documentation
+urlpatterns += [
+    path(
+        "openapi",
+        get_schema_view(
+            title=settings.SITE_NAME,
+            description=f"{settings.SITE_NAME} REST API",
+            version=settings.API_VERSION,
+            patterns=api_patterns,
+        ),
+        name="openapi-schema",
+    ),
+    path(
+        "swagger/",
+        TemplateView.as_view(
+            template_name="swagger-ui.html", extra_context={"schema_url": "openapi-schema"}
+        ),
+        name="swagger-ui",
+    ),
+    path(
+        "redoc/",
+        TemplateView.as_view(
+            template_name="redoc.html", extra_context={"schema_url": "openapi-schema"}
+        ),
+        name="redoc",
+    ),
+]
 
 if settings.DEBUG:
     # This allows the error pages to be debugged during development, just visit

diff --git a/mycarehub/templates/redoc.html b/mycarehub/templates/redoc.html
@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>ReDoc</title>
+    <!-- needed for adaptive design -->
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+    <!-- ReDoc doesn't change outer page styles -->
+    <style>
+        body {
+            margin: 0;
+            padding: 0;
+        }
+    </style>
+</head>
+
+<body>
+    <redoc spec-url='{% url schema_url %}'></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
+</body>
+
+</html>
diff --git a/mycarehub/templates/swagger-ui.html b/mycarehub/templates/swagger-ui.html
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+    <title>Swagger</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
+</head>
+
+<body>
+    <div id="swagger-ui"></div>
+    <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+    <script>
+        const ui = SwaggerUIBundle({
+            url: "{% url schema_url %}",
+            dom_id: '#swagger-ui',
+            presets: [
+                SwaggerUIBundle.presets.apis,
+                SwaggerUIBundle.SwaggerUIStandalonePreset
+            ],
+            layout: "BaseLayout",
+            requestInterceptor: (request) => {
+                request.headers['X-CSRFToken'] = "{{ csrf_token }}"
+                return request;
+            }
+        })
+    </script>
+</body>
+
+</html>