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

Deploy Swagger APIs to IBM Cloud Private using IBM Cloud Developer ToolsErnese NorelusBlockedUnblockFollowFollowingMay 13A RESTful API approachEmployee Swagger APIWhile 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 GitHubI 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?WalkthroughHere 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 prerequisitesBuild and run the application locally – Inspect the generated code- Modify the default generated response – Run the IBM Tool Dev- Deploy and test the codeDeploy 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 codePrerequisitesBefore 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 PrivateIBM Cloud Developer ToolsInstallationSecondly, 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 Javainstall jqinstall Maveninstall IBM Cloud Developer Tools CLIinstall Swagger codegen cliConfig Swagger and installation fileBuild and run the application locallyBefore 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 — CreateGET: consult and read resources — ReadPUT: edit resources — UpdateDELETE: eliminate resources — DeleteSwagger 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.

yamlLet’s create a CRUD Spring Boot RESTFul web services with the command below:swagger code generatorShow 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 genInspect the generated codeThe 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.

javaThe 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 filesA 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 responsecd ~/artefacts/employeeWe 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 enableThese files contain commands to create Docker images for both IBM Cloud and IBM Cloud Private deployment.

List files after ibmcloud generated filesThere 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 buildibmcloud dev runRun the Spring programLaunching 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 UINow navigate to http://localhost:8080/v1/employees/1234, and you will get the following:GET employee 1234 deployed locallyFrom command line run curl -X GET –header 'Accept: application/json' 'http://192.

168.

27.

100:30527/v1/employees/1234' | jqand you will get:% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 134 0 134 0 0 3828 0 –:–:– –:–:– –:–:– 4322{ "id": 0, "firstName": "firstname", "lastName": "NlastName",}Deploy the application to IBM Cloud PrivateYou can follow the detail instructions for this setup here Install the IBM IBM Cloud Developer ToolsLet’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 MicroserviceLog in and Choose a ClusterConfigure for Docker Registry AccessConfigure kubectlDeploy Helm ChartREST-ful Interaction using Swagger ConsoleREST-ful Interaction using curlLogin into ICP via UILog in to IBM Cloud Private web console with https://192.

168.

27.

100:8443/, the default credentials are: login: adminpassword: adminTo 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 detailsCreate namespace in ICPCreate namespace employeekubectl 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 ICPAuthenticate to the ICP Private Docker Registrydocker imagesemployee image on DockerConfigure docker service to use insecure registryConfigure docker serviceLogin to docker registryPrepare to push the Docker image to the ICP Private Docker RegistryBefore 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 tagConfigure images for helmConfigure employee in the chart directory to later run on helmConfigure images for helmInstall cloudctlInstall cloudctl from ICPInstall helmInstall helm from ICPBuilding and deploying the app in IBM Cloud PrivateLog 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 ICPDeploy helm to IBM Cloud PrivateDeploy helm to ICPIssue kubectl command against pods and serversTry APII 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 similarGET employee 1234 deployed on ICPConclusionIn 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 Cloud Garage.

Thoughts and ideas are greatly appreciated!AttributionSpecial thank you to Enrique (Ike) Relucio from IBM Cloud 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!ReferencesConfiguring pod security policiesDeploying Helm charts that require elevated privileges in a non-default namespaceCreating imagePullSecrets for a specific namespaceAdding a pod security policy binding to a namespaceLet’s understand what an API isWhat is an API?.In English, please.

RESTful API Designing guidelines — The best practices.

. More details

Leave a Reply