Deploy Swagger APIs to IBM Cloud Private using IBM Cloud Developer Tools

A RESTful API approach

Employee Swagger API

While working on a project, my client asked if I could quickly demo how to take their Swagger API file and deploy this into IBM Cloud Private (an application platform for developing and managing on-premises, containerized applications using Kubernetes as an orchestrator) also called ICP, with minimal effort and sell the value of ICP and IBM tooling. A nice challenge that makes a whole lot of sense if I could demo this on the fly. A lot rested on my shoulders and had to show that it was possible to whip one out quickly.

I asked if I needed to integrate with their back-end database and the answer was no, luckily as this would have required more thinking to come with such scenario on the fly. I will walk you through the demo step-by-step; of course, I did make that happen, and now I’m documenting this, I’m in a better position to come up with something more meaningful.

I took a sample Swagger API file from swagger.io and extended with additional POST, PUT, DELETE verbs ; I could explore REST APIs and the desired implementation language. Java was a safe bet for me, although I could have used Python, Node.js or any other programming languages supported by Swagger Code Generator.

I have since turned this to a demo, and now, I have something to show if a similar request comes about. I’d love it if you would follow along and code alongside me.

This blog post is going through the steps required to deploy a Swagger API on IBM Cloud Private; I’ll create a Java Spring Microservice using Swagger Code Generator and IBM Cloud Tools and implementing it into a running Kubernetes Cluster to consume RESTful services.

For this, I use a more systematic approach to building this demo and overcomes some of the challenges faced along the way and the workarounds, and all this can be found as a project on my GitHub

I will create a RESTful API that is used to store employees details, which has CRUD (Create, Read, Update, Delete) functions, allowing us to create new employees, get details of existing employees, update details of existing employees and delete existing employees. All of this by using Java API running on ICP, for what I’m going to show the Swagger Codegen automatically generates a considerable part of the code and saves you tons of time building an integrated app.

Enough with the small talk, let’s get down to business, shall we?

Walkthrough

Here are the steps required for you to reproduce this demo if needed, where an explanation will follow every snippet of code; we need to set up and install the dependencies required for the app to work correctly, no database is needed; perhaps, subject of a future blog.

• Prepare the necessary environment for the demo (step-by-step) with prerequisites
• Build and run the application locally
  - Inspect the generated code
  - Modify the default generated response
  - Run the IBM Tool Dev
  - Deploy and test the code
• Deploy the application to IBM Cloud Private
  - Login into ICP via UI
  - Create namespace in ICP
  - Authenticate to the ICP Private Docker Registry
  - Configure docker service to use insecure registry
  - Prepare to push the Docker image to the ICP Private Docker Registry
  - Configure images for helm
  - Install cloudctl
  - Install helm
  - Building and deploying the app in IBM Cloud Private
  - Deploy helm to IBM Cloud Private
  - Deploy and test the code

Prerequisites

Before I begin, there are some things I need to do: download these tools for the demo the work, so make sure you have these installed before you proceed any further.

• Spring (for Spring REST applications)
• Swagger UI (accessing the API using a browser)
• Swagger Codegen (generate client code stubs)
• IBM Cloud Private
• IBM Cloud Developer Tools

Installation

Secondly, you are required to have these applications installed, to simplify things. I have created a git repo with the steps needed so that you can reproduce the demo if you need a local instance running on a vagrant box with IP 192.168.99.156; an instance of IBM Cloud Private in a vagrant box with IP 192.168.27.100 can also be found here, but you are required at least 16 GB RAM and 250 GB HDD to run it.

• install Java
• install jq
• install Maven
• install IBM Cloud Developer Tools CLI
• install Swagger codegen cli

Config Swagger and installation file

Build and run the application locally

Before we start all, let’s have a quick refresher on REST and its operations and how to use this in the demo; REST stand for REpresentational State Transfer a type of web development architecture that is fully supported by the HTTP standard. REST support these four verbs/operations primarily, Create, Read, Update and Delete, also knows as CRUD that maps to your database trigger/operations to manipulate resources, HTTP gives us the following methods with which we must operate:

• POST: create resources — Create
• GET: consult and read resources — Read
• PUT: edit resources — Update
• DELETE: eliminate resources — Delete

Swagger is a language-agnostic interface to REST APIs with a specification for describing, producing, consuming, testing, and visualizing a RESTful API. It provides several tools for automatically generating documentation based on a given endpoint.

By running the Swagger Codegen on employee.yaml we will generate a default server-side implementation of our API microservices using Java and Spring. All project artifacts and directories are created in the current directory.

Swagger is also known as OpenAPI, a blueprint for your APIs, a widely used standard for specifying and documenting REST Services mentioned above.

Let’s jump right in to understand it.

The interface is rendered by Swagger Codegen; this model will serve as a blueprint showing what all users in your CRUD will look like.

The Swagger file employee.yaml is shown below:

Employee.yaml

Let’s create a CRUD Spring Boot RESTFul web services with the command below:

swagger code generator

Show Swagger file here:

After running the above command, we can inspect the directory to see the generated code including src and pom.xml; Maven projects are defined with an XML file named pom.xml, while the src contains the source files, such as Java classes addressed in section “Inspect the generated code”

List code from Swagger code gen

Inspect the generated code

The API’s basePath, ‘api/v1’

Now our employee code is generated from our Swagger specification and will be available as customer-facing documentation when we run our app. Let’s access the REST service through Swagger and REST client to see the default response and change.

EmployeesApiController.java

The default code generated by Swagger Codegen returns HTTP Status Code 501 (NOT_IMPLEMENTED) for all the endpoints in the employee.yaml file hence the need to modify the code to change this behavior.

Edit Swagger class files

A few things are required to update the files and get this demo working: I’ve overwritten the default documentation from NOT_EMPLEMENTED to OK Modifying the default generated response.

Modify EmployeesApiController.java file from default generated response

cd ~/artefacts/employee

We can now run this locally; the purpose of running ibmcloud dev enable it to generate artefacts that we need to Dockerize our application and deploy our application to IBM Cloud private using Helm charts.

echo "y" | ibmcloud dev enable

These files contain commands to create Docker images for both IBM Cloud and IBM Cloud Private deployment.

List files after ibmcloud generated files

There is so much more to IBM Tool Dev, but for now, we are only going to use these two commands ibmcloud dev build and ibmcloud dev run; these actions will inspect the project to determine the primary language. The identified language will then be used to generate language-specific assets that will be utilized for deployment to IBM Cloud and here it's Java Spring.

ibmcloud dev build
ibmcloud dev run

Run the Spring program

Launching Swagger UI; Swagger UI is the beautiful view we see when we document our api with swagger. The README of the project defines it this way; now navigate to http://192.168.99.156:8080/v1/swagger-ui.html , the Swagger 2-generated documentation now looks similar to this:

Swagger Employee Details Demo UI

Now navigate to http://localhost:8080/v1/employees/1234, and you will get the following:

GET employee 1234 deployed locally

From command line run curl -X GET --header 'Accept: application/json' 'http://192.168.27.100:30527/v1/employees/1234' | jq

and you will get:

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   134    0   134    0     0   3828      0 --:--:-- --:--:-- --:--:--  4322
{
  "id": 0,
  "firstName": "firstname",
  "lastName": "NlastName",
}

Deploy the application to IBM Cloud Private

You can follow the detail instructions for this setup here Install the IBM IBM Cloud Developer Tools

Let’s continue with what was created from the previous section on the Spring Microservice creation.

Now, we have a few more steps to get this to run on ICP:

• Creating a Spring Microservice
• Log in and Choose a Cluster
• Configure for Docker Registry Access
• Configure kubectl
• Deploy Helm Chart
• REST-ful Interaction using Swagger Console
• REST-ful Interaction using curl

Login into ICP via UI

Log in to IBM Cloud Private web console with https://192.168.27.100:8443/, the default credentials are: login: admin

password: admin

To get the configuration information, click the user icon in the upper right corner of the screen, and select configure client. The screen displays the configuration information for your cluster that you need to copy and paste into a terminal window where you will be using the kubectl command line interface.

ICP Configure client details

Create namespace in ICP

Create namespace employee

kubectl create namespace employee To register the namespace employee on ICP, they are a few ways to go about this, here is my favorite:

config cluster with ICP

Authenticate to the ICP Private Docker Registry

docker images

employee image on Docker

Configure docker service to use insecure registry

Configure docker service

Login to docker registry

Prepare to push the Docker image to the ICP Private Docker Registry

Before you can successfully push a Docker image to the ICP Private Docker Registry, there are two things that you must do to prepare:

• ICP must have a namespace that matches the name of the repository within the registry that you are storing the Docker image in.
• The Docker image must be prefixed with the URI for the ICP Private Docker Registry.

Docker tag

Configure images for helm

Configure employee in the chart directory to later run on helm

Configure images for helm

Install cloudctl

Install cloudctl from ICP

Install helm

Install helm from ICP

Building and deploying the app in IBM Cloud Private

Log in with the credentials shown below and select your namespace where you want to deploy the application, in this case, select 3, which equates to employee the namespace created in section Create namespace in ICP.

Deploy employee app on ICP

Deploy helm to IBM Cloud Private

Deploy helm to ICP

Issue kubectl command against pods and servers

Try API

I used curl to make GET and POST requests from the terminal. Let’s break down the code snippet above into smaller parts to understand it better. We’ll explore the GET endpoint. The functionality of POST would be very similar

GET employee 1234 deployed on ICP

Conclusion

In this blog post, I’ve walked you through the workings of Swagger Code Generator, IBM Cloud Tools and IBM Cloud Private. I took a Swagger file generated microservices with swagger-codegen, built and ran the application locally as the first phase of the demo, and tested it against IBM Cloud Private with the respective REST APIs and CRUD operations.

I hope you found the topic interesting; the complete code can be found in this git repository: https://github.com/ernesen/swagger-icp.git and I hope you consider using IBM Cloud Developer Tools CLI and IBM Cloud Private for your next project!

For more interesting topics on IBM Cloud and IBM Cloud Private don’t forget to visit the IBM Garage.

Thoughts and ideas are greatly appreciated!

Attribution

Special thank you to Enrique (Ike) Relucio from IBM Garage ASEAN, who was instrumental a getting me on the right path by helping with some docker related topics and suggested some best practice around building Swagger APIs, in addition to testing and reviewing this demo!

References

• Configuring pod security policies
• Deploying Helm charts that require elevated privileges in a non-default namespace
• Creating imagePullSecrets for a specific namespace
• Adding a pod security policy binding to a namespace
• Let’s understand what an API is
• What is an API? In English, please.
• RESTful API Designing guidelines — The best practices

Bring your plan to the IBM Garage.
Are you ready to learn more about working with the IBM Garage? We’re here to help. Contact us today to schedule time to speak with a Garage expert about your next big idea. Learn about our IBM Garage Method, the design, development and startup communities we work in, and the deep expertise and capabilities we bring to the table.

Schedule a no-charge visit with the IBM Garage.