jupyter-servergh-1418: swagger-ui-dist strawman

.gitignore

@@ -9,6 +9,7 @@ docs/gh-pages
 jupyter_server/i18n/*/LC_MESSAGES/*.mo
 jupyter_server/i18n/*/LC_MESSAGES/nbjs.json
 jupyter_server/static/style/*.min.css*
+jupyter_server/static/vendor/
 node_modules
 *.py[co]
 __pycache__

jupyter_server/services/api/handlers.py

@@ -43,6 +43,18 @@ def get_content_type(self):
         return "text/x-yaml"
 
 
+class APIDocsHandler(JupyterHandler):
+    """A handler for the documentation of the REST API."""
+
+    auth_resource = AUTH_RESOURCE
+
+    @web.authenticated
+    @authorized
+    async def get(self):
+        """Get the REST API documentation."""
+        return self.finish(self.render_template("apidocs.html"))
+
+
 class APIStatusHandler(APIHandler):
     """An API status handler."""
 
@@ -115,6 +127,7 @@ async def get(self):
 
 
 default_handlers = [
+    (r"/api/apidocs", APIDocsHandler),
     (r"/api/spec.yaml", APISpecHandler),
     (r"/api/status", APIStatusHandler),
     (r"/api/me", IdentityHandler),

jupyter_server/templates/apidocs.html

@@ -0,0 +1,27 @@
+{% extends "page.html" %}
+
+{% block stylesheet %}
+    {{ super() }}
+    <link rel="stylesheet" href="{{ static_url('vendor/swagger-ui-dist/swagger-ui.css') }}" />
+    <style>
+        .swagger-ui .info .title small pre {
+            background-color: transparent;
+            border: 0;
+        }
+    </style>
+{% endblock stylesheet %}
+
+{% block site %}
+    <div id="swagger-ui"></div>
+{% endblock site %}
+
+{% block script %}
+    {{ super() }}
+    <script src="{{ static_url('vendor/swagger-ui-dist/swagger-ui-bundle.js') }}"></script>
+
+    <script>
+        ;(function(){
+            SwaggerUIBundle({ url: "./spec.yaml", dom_id: "#swagger-ui" });
+        }).call(this);
+    </script>
+{% endblock script %}

package.json

@@ -4,11 +4,14 @@
   "version": "1.0.0",
   "license": "BSD",
   "scripts": {
-    "build": "copyfiles -f node_modules/bootstrap/dist/css/*.min.* jupyter_server/static/style"
+    "build": "npm run build:bootstrap && npm run build:swagger-ui",
+    "build:bootstrap": "copyfiles -f node_modules/bootstrap/dist/css/*.min.* jupyter_server/static/style",
+    "build:swagger-ui": "copyfiles -f \"node_modules/swagger-ui-dist/{NOTICE,LICENSE}\" \"node_modules/swagger-ui-dist/swagger-ui{.css,-bundle.js}\" jupyter_server/static/vendor/swagger-ui"
   },
   "dependencies": {
     "bootstrap": "^3.4.0",
-    "copyfiles": "^2.4.1"
+    "copyfiles": "^2.4.1",
+    "swagger-ui-dist": "^5.17.2"
   },
   "eslintIgnore": [
     "*.min.js",

pyproject.toml

@@ -133,9 +133,16 @@ dependencies = ["hatch-jupyter-builder>=0.8.1"]
 build-function = "hatch_jupyter_builder.npm_builder"
 ensured-targets = [
   "jupyter_server/static/style/bootstrap.min.css",
-  "jupyter_server/static/style/bootstrap-theme.min.css"
+  "jupyter_server/static/style/bootstrap-theme.min.css",
+  "jupyter_server/static/vendor/swagger-ui/dist/dist/swagger-ui.css",
+  "jupyter_server/static/vendor/swagger-ui/dist/swagger-ui-bundle.js",
+  "jupyter_server/static/vendor/swagger-ui/LICENSE",
+  "jupyter_server/static/vendor/swagger-ui/NOTICE",
+]
+skip-if-exists = [
+  "jupyter_server/static/style/bootstrap.min.css",
+  "jupyter_server/static/vendor/swagger-ui/dist/swagger-ui-bundle.js",
 ]
-skip-if-exists = ["jupyter_server/static/style/bootstrap.min.css"]
 install-pre-commit-hook = true
 optional-editable-build = true
 

tests/base/test_handlers.py

@@ -13,6 +13,7 @@
 from jupyter_server.auth.decorator import allow_unauthenticated
 from jupyter_server.base.handlers import (
     APIHandler,
+    APIDocsHandler,
     APIVersionHandler,
     AuthenticatedFileHandler,
     AuthenticatedHandler,
@@ -238,6 +239,15 @@ async def test_api_version_handler(jp_serverapp):
     assert handler.get_status() == 200
 
 
+async def test_api_docs_handler(jp_serverapp):
+    app: ServerApp = jp_serverapp
+    request = HTTPRequest("GET")
+    request.connection = MagicMock()
+    handler = APIDocsHandler(app.web_app, request)
+    handler.get()
+    assert handler.get_status() == 200
+
+
 async def test_files_redirect_handler(jp_serverapp):
     app: ServerApp = jp_serverapp
     request = HTTPRequest("GET")