Strawman API Docs

.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,swagger-ui.css,swagger-ui-bundle.js}\" jupyter_server/static/vendor/swagger-ui-dist"
   },
   "dependencies": {
     "bootstrap": "^3.4.0",
-    "copyfiles": "^2.4.1"
+    "copyfiles": "^2.4.1",
+    "swagger-ui-dist": "^5.17.2"
   },
   "eslintIgnore": [
     "*.min.js",

pyproject.toml

@@ -126,16 +126,26 @@ path = "jupyter_server/_version.py"
 validate-bump = false
 
 [tool.hatch.build]
-artifacts = ["jupyter_server/static/style"]
+artifacts = [
+  "jupyter_server/static/style",
+  "jupyter_server/static/vendor",
+]
 
 [tool.hatch.build.hooks.jupyter-builder]
 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/LICENSE",
+  "jupyter_server/static/vendor/swagger-ui-dist/NOTICE",
+  "jupyter_server/static/vendor/swagger-ui-dist/swagger-ui-bundle.js",
+  "jupyter_server/static/vendor/swagger-ui-dist/swagger-ui.css",
+]
+skip-if-exists = [
+  "jupyter_server/static/style/bootstrap.min.css",
+  "jupyter_server/static/vendor/swagger-ui-dist/swagger-ui.css",
 ]
-skip-if-exists = ["jupyter_server/static/style/bootstrap.min.css"]
 install-pre-commit-hook = true
 optional-editable-build = true
 

tests/services/api/test_api.py

@@ -13,6 +13,11 @@ async def test_get_spec(jp_fetch):
     assert response.code == 200
 
 
+async def test_get_api_docs(jp_fetch):
+    response = await jp_fetch("api", "apidocs", method="GET")
+    assert response.code == 200
+
+
 async def test_get_status(jp_fetch):
     response = await jp_fetch("api", "status", method="GET")
     assert response.code == 200