Notebook Microservice And Swagger

Share: Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditEmail this to someonePrint this page

In previous posts we learned how to create a microservice in a notebook using the Jupyter kernel gateway. This will be the foundation for today’s post where we will be creating a notebook microservice with Swagger, a set of tools for representing REST APIs. With this this approach, notebook authors can create and deploy APIs that are easy-to-comsume by other developers.

There are many components to Swagger, but today we will be using three. The first component, the Swagger Specification, is a specification we will use to describe out microservice. The second is a code generation plugin to generate our notebook. And finally, we will use the Swagger UI to interact with our newly deployed service.

Setup and Introduction

There is some initial setup needed for this demo:

While all of that is installing, let’s look at reasons for integrating Swagger in our microservice workflow.

  • Clear API Definition – The Swagger Specification is a standard way for describing our microservice API. This allows for the rapid and collaborative design of what our API will look like.
  • Quick Code Generation – Using a standard way to describe our microservice opens up a suite of tools for generating code. Today we will generate a notebook, but there are also tools for generating other client and server side pieces of code.
  • Easy API Testing – Another advantage of describing our microservice in a standard way is the use of tools for testing. An example of this is the Swagger UI, which we will use today, for manually verifying the behavior of API endpoints.

Designing The Microservice

Our microservice will be used to create and get random quotes. Our service is defined by the following API endpoints:

  • An endpoint to display random quote
  • An endpoint to add new quotes
  • And endpoint to get a quote
  • An endpoint to update a quote

We now need a way to describe this API so Swagger can generate a specification for us. I used the Swagger Editor to design this API in YAML. The code snippet below is the definition for the full API specification.

With the microservice defined, we can export it to a JSON file. You can do this in the Swagger Editor by going to File -> ‘Download JSON’.

Generating The Notebook

Once you have the JSON file describing the microservice, navigate to the kernel gateway demos project on your system. You will need to open a command line utility here and go to the directory swagger-notebook-service/jupyter-swagger-codegen. From this directory we will generate the notebook to implement our microservice. The language for the generated notebook defaults to Python 3. You can generate the notebook with the following command:

path/to/swagger.json  is the JSON file you downloaded earlier from the Swagger Editor. If you did not create your own swagger.json file, use this url to download a completed copy. The command should have generated the following files in target/swagger/python3/WordsOfWisdom/src/:

  • WordsOfWisdomApi.ipynb – The notebook where the service will be implemented
  • – Bundles the notebook with the kernel gateway into a Docker container
  • –  Runs the Docker container built by
  • Dockerfile – A Dockerfile that defines Docker container image

Authoring And Running The Microservice

For the sake of brevity, there is a sample notebook with the implemented API endpoints. You can download this file and put the contents into the   WordsOfWisdomApi.ipynb file.

From here you can build and deploy the microservice locally with Docker by running:

When everything is built correctly, you should see output similar to the following:

With the service successfully running, you will be able to access the API endpoints. Use the ip address for your Docker host and go to:  http://YOUR_DOCKER_HOST:8888/random. This endpoint will display a random quote, served from our notebook.

Consuming The Swagger Spec

Our final step will be to use the Swagger UI to interact with our API. The kernel gateway will automatically generate a simple Swagger Specification for consumption through the Swagger UI. The specification can be found at  http://YOUR_DOCKER_HOST:8888/_api/spec/swagger.json. You will need to enter the spec URL into the Swagger UI. The picture below shows how to use the Swagger UI to make requests to the microservice.
Swagger UI Microservice
Note: The generated swagger spec is still under development and you will not be able to interact with all endpoints. As a temporary alternative, you can use the Swagger Editor for interacting with the microservice. If you have a need for a requirement pull requests and issues are welcome.


In this post you have seen how integrating Swagger into the microservice workflow has helped our development process. If you have any questions or want to get involved with the kernel gateway visit our github repo.

Learn More

Share: Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInShare on RedditEmail this to someonePrint this page
Corey Stubbs

Latest posts by Corey Stubbs (see all)

Corey Stubbs