add support for OpenAPI rendering via ReDoc (#414) (#720)

* add support for OpenAPI rendering via ReDoc (#414) * add support for OpenAPI rendering via ReDoc (#414)
2021-06-30 11:11:57 -04:00
parent 7ecac02693
commit 167281ee83
6 changed files with 45 additions and 4 deletions
@@ -21,8 +21,8 @@ The API is accessible at the ``/openapi`` endpoint, providing a Swagger-based we
   the pygeoapi demo OpenAPI/Swagger endpoint at https://demo.pygeoapi.io/master/openapi


-Using OpenAPI
-------------
+Using OpenAPI via Swagger
+-------------------------

 Accessing the Swagger webpage we have the following structure:

@@ -62,6 +62,13 @@ This identifier can be used to obtain a specific item from the dataset using the

 .. image:: /_static/openapi_get_item_id2.png

+Using OpenAPI via ReDoc
+-----------------------
+
+pygeoapi also supports OpenAPI document rendering via `ReDoc <https://redoc.ly/>`_.
+
+ReDoc rendering is accessible at the same ``/openapi`` endpoint, adding ``ui=redoc`` to the request URL.
+
 Summary
 -------

@@ -629,13 +629,18 @@ class API:
            return self.get_format_exception(request)

        headers = request.get_response_headers()
+
        if request.format == F_HTML:
+            template = 'openapi/swagger.html'
+            if request._args.get('ui') == 'redoc':
+                template = 'openapi/redoc.html'
+
            path = '/'.join([self.config['server']['url'].rstrip('/'),
                            'openapi'])
            data = {
                'openapi-document-path': path
            }
-            content = render_j2_template(self.config, 'openapi.html', data,
+            content = render_j2_template(self.config, template, data,
                                         request.locale)
            return headers, 200, content

@@ -68,7 +68,7 @@
  <section id="openapi">
      <h2>API Definition</h2>
      <p>
-        <a href="{{ config['server']['url'] }}/openapi?f=html">Documentation</a>
+        Documentation: <a href="{{ config['server']['url'] }}/openapi?f=html">Swagger UI</a> <a href="{{ config['server']['url'] }}/openapi?f=html&ui=redoc">ReDoc</a>
      </p>
      <p>
        <a href="{{ config['server']['url'] }}/openapi?f=json">OpenAPI Document</a>
@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>ReDoc - {{ config['metadata']['identification']['title'] }}</title>
+    <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">
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <redoc spec-url='{{ data['openapi-document-path'] }}?f=json'></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
+  </body>
+</html>
@@ -208,6 +208,16 @@ def test_api(config, api_, openapi):
    assert rsp_headers['Content-Type'] == FORMAT_TYPES[F_HTML] == \
           FORMAT_TYPES[F_HTML]

+    assert 'Swagger UI' in response
+
+    a = 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8'
+    req = mock_request({'ui': 'redoc'}, HTTP_ACCEPT=a)
+    rsp_headers, code, response = api_.openapi(req, openapi)
+    assert rsp_headers['Content-Type'] == FORMAT_TYPES[F_HTML] == \
+           FORMAT_TYPES[F_HTML]
+
+    assert 'ReDoc' in response
+
    req = mock_request({'f': 'foo'})
    rsp_headers, code, response = api_.openapi(req, openapi)
    assert rsp_headers['Content-Language'] == 'en-US'