Merge pull request #142 from Lull3rSkat3r/issue-135-add-swagger-spec

[Issue 135]: Add swagger specs for jupyter-websocket mode

README.md

@@ -102,3 +102,12 @@ straightforward using these steps:
       route `/api/kernels` is not enabled by default for greater security. See
       the `--KernelGatewayApp.list_kernels` parameter documentation if you
       would like to enable the `/api/kernels` route.)
+
+### Swagger Documentation
+
+When adding features to the `jupyter-websocket` handlers, documentation needs to
+be added to the project's swagger specifications. You can import the current
+[yaml](https://github.com/jupyter/kernel_gateway/tree/master/kernel_gateway/services/api/swagger.yaml)
+file into the swagger editor and add your changes. Upon completion, export both
+the `swagger.json` and `swagger.yaml` files and place them in
+[`kernel_gateway/services/api`](https://github.com/jupyter/kernel_gateway/tree/master/kernel_gateway/services/api).

docs/source/websocket-mode.md

@@ -1,21 +1,7 @@
 ## `jupyter-websocket` Mode
 
-The `KernelGatewayApp.api` command line argument defaults to 
-`jupyter-websocket`. In this mode, the kernel gateway defines the following
-web resources:
-
-* `/api` (metadata)
-* `/api/kernelspecs` (what kernels are available)
-* `/api/kernels` (kernel CRUD, with discovery disabled by default,
-  see `--list_kernels`)
-* `/api/kernels/:kernel_id/channels` (Websocket-to-[ZeroMQ](http://zeromq.org/) 
-  transformer for the [Jupyter kernel protocol](http://jupyter-client.readthedocs.org/en/latest/messaging.html))
-* `/api/sessions` (session CRUD, for associating information with kernels,
-  discovery disabled by default, see `--list_kernels`)
-* `/_api/activity` (activity metrics for all running kernels, enabled with
-  `--list_kernels`)
-
-Discounting features of the kernel gateway (e.g., token auth), the behavior
-of these resources is equivalent to that found in the Jupyter Notebook server.
-The kernel gateway simply imports and extends the handler classes from
-the Jupyter Notebook.
+The `KernelGatewayApp.api` command line argument defaults to
+`jupyter-websocket`. The API exposed in this mode can be viewed
+in the [swagger ui.](http://petstore.swagger.io) by entering
+the link to the [swagger spec](https://raw.githubusercontent.com/jupyter/kernel_gateway/master/kernel_gateway/services/api/swagger.json)
+of kernel gateway.

kernel_gateway/gatewayapp.py

@@ -25,6 +25,7 @@
 from tornado import web
 from tornado.log import enable_pretty_logging
 
+from .services.api.handlers import default_handlers as default_api_handlers
 from .services.kernels.handlers import default_handlers as default_kernel_handlers
 from .services.kernelspecs.handlers import default_handlers as default_kernelspec_handlers
 from .services.sessions.handlers import default_handlers as default_session_handlers
@@ -362,6 +363,7 @@ def init_webapp(self):
             ))
             # append tuples for the standard kernel gateway endpoints
             for handler in (
+                default_api_handlers +
                 default_kernel_handlers +
                 default_kernelspec_handlers +
                 default_session_handlers +

kernel_gateway/mixins.py

@@ -26,7 +26,6 @@ def set_default_headers(self):
         for a programmatic API.
         """
         super(CORSMixin, self).set_default_headers()
-
         # Add CORS headers after default if they have a non-blank value
         for settings_name, header_name in self.SETTINGS_TO_HEADERS.items():
             header_value = self.settings.get(settings_name)

kernel_gateway/services/api/handlers.py

@@ -0,0 +1,52 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+"""Tornado handlers for kernel specs."""
+
+from tornado import web
+from ...mixins import TokenAuthorizationMixin, CORSMixin, JSONErrorsMixin
+import os
+
+class BaseSpecHandler(CORSMixin, web.StaticFileHandler):
+    """Exposes the ability to return specifications from static files"""
+    @staticmethod
+    def get_resource_metadata():
+        """Returns the (resource, mime-type) for the handlers spec.
+        """
+        pass
+
+    def initialize(self):
+        """Initializes the instance of this class to serve files.
+
+        The handler is initialized to server files from the directory
+        where this module is defined.
+        """
+        web.StaticFileHandler.initialize(self, path=os.path.dirname(__file__))
+
+    def get(self):
+        """Handler for a get on a specific handler
+        """
+        resource_name, content_type = self.get_resource_metadata()
+        self.set_header('Content-Type', content_type)
+        return web.StaticFileHandler.get(self, resource_name)
+
+    def options(self, **kwargs):
+        """Method for properly handling CORS pre-flight"""
+        self.finish()
+
+class SpecJsonHandler(BaseSpecHandler):
+    """Exposes a JSON swagger specification"""
+    @staticmethod
+    def get_resource_metadata():
+        return ('swagger.json','application/json')
+
+class APIYamlHandler(BaseSpecHandler):
+    """Exposes a YAML swagger specification"""
+    @staticmethod
+    def get_resource_metadata():
+        return ('swagger.yaml', 'text/x-yaml')
+
+
+default_handlers = [
+    ('/api/{}'.format(SpecJsonHandler.get_resource_metadata()[0]), SpecJsonHandler),
+    ('/api/{}'.format(APIYamlHandler.get_resource_metadata()[0]), APIYamlHandler)
+]