A Beginner's Guide To Integrate Swagger With Oracle API Gateway & Functions

Swagger API documentation generation and integration with Oracle API Gateway

Overview

This blog will explain how to generate Swagger API Documentation using Swagger Editor and run Swagger UI locally on a compute instance and integrate Swagger UI with the Oracle API Gateway. I will put Oracle blogs link on the creation of API Gateway and functions.

Note: Here I have created architecture in Oracle Cloud Infrastructure but If you are using AWS or Azure then also this blog will help you because to integrate swagger with API Gateway we need to do changes in the swagger file.

Content:

1. Architecture Setup
2. Swagger Editor Installation
3. Swagger UI & API Gateway Integration

1. Architecture Setup

OCI Architecture for Swagger by Vikas Gautam

1. Virtual Cloud Network

First, we will create a VCN with Internet Gateway, for this steps are:

1. Open the navigation menu, select Networking, and then select Virtual Cloud Networks (Ensure that the correct compartment is selected in the Compartment list).
2. Click Start VCN Wizard.
3. Select VCN with Internet Connectivity, and then click Start VCN Wizard.
4. Fill VCN name and select compartment, for CIDR block, private and public subnet range choose default values (CIDR=10.0.0.0/16, private subnet=10.0.0.0/24, public subnet=10.0.1.0/24)

Here Wizard will create VCN and add Internet and Service Gateway, also we do not need to do routing because Wizard will take care of it.

2. Virtual Machine

We will create a compute instance in the public subnet of VCN and for the image, we will choose Centos7.

Steps to create compute instance are:

1. Open the navigation menu and click Compute. Under Compute, click Instances.
2. Click Create Instance.
3. Enter a name for the instance.
4. Choose Centos7 image.
5. Shape AMD processors 1 GB & 1 OCPU.
6. Choose existing VCN and public subnet, also assign Public IP.
7. Generate or upload key for ssh.
8. Create instance.

Once the instance is created then you will see public IP attached to the instance, this public IP will be used to access swagger UI.

3. Functions

We will create an Oracle Application and then inside this application we will create a function and deploy it on the Oracle container registry.

Once it is done you can use the command fn invoke <application> <function> and check the response of the function.

To create Oracle functions, follow this blog https://docs.oracle.com/en-us/iaas/Content/Functions/Tasks/functionsuploading.htm

4. API Gateway

We will create an Oracle Gateway of type public and inside this Gateway, we will create a deployment. Once it is done then you will have the endpoint of deployment which will look like https:asdafrgsvsgwg.../<path-prefix>/<path>

To create API Gateway and add oracle functions or Rest APIs follow this blog https://blogs.oracle.com/developers/creating-your-first-api-gateway-in-the-oracle-cloud

2. Swagger Editor Installation

We will install swagger editor on a compute instance that we have created on the public subnet. Steps to install swagger on compute instance are

1. SSH to the instance using putty and logic with the user opc.
2. Install Git using command sudo yum install git.
3. Install Docker https://docs.docker.com/engine/install/centos/
4. Pull swagger editor image & run it

sudo docker pull swaggerapi/swagger-editor
sudo docker run -d -p 80:8080 swaggerapi/swagger-editor

5. Add security rules in the public subnet security list

0.0.0.0/0    TCP    ALL    443
0.0.0.0/0    TCP    ALL    80
0.0.0.0/0    TCP    ALL    3001

Get public Ip of this instance from OCI console and paste it on browser, you will see swagger editor page having pet store project.

For more information about the swagger editor, follow this GitHub link https://github.com/swagger-api/swagger-editor

3. Swagger UI & API Gateway Integration

First we will generate swagger API documentation using Swagger Editor.

For this, we only need to provide Host and Path Prefix of our Gateway Deployment to Swagger editor yaml file.

The Gateway host will look like https://asdassdf....com

Edit swagger editor YAML file line number 12 & 13 and your Base URL will change into https://<Gateway Host>/<path-prefix>

After this, you can replace /pet and method present inside paths with your path and method.

So complete URL will become https://<Gateway Host>/<path-prefix>/pet when you hit an API, you can verify this URL by checking the curl command that the swagger editor is hitting.

Once you are done with the changes save the file either in YAML or JSON format and pull swagger-ui docker image and run Swagger UI, Please note in the below example I am assuming that the swagger.yaml file is present in ./home/opc/swagger.yaml.

sudo docker pull swaggerapi/swagger-ui
sudo docker run -d -p 3001:8080 -v /home/opc/swagger.yaml:/swagger.yaml -e SWAGGER_JSON=/swagger.yaml  swaggerapi/swagger-ui

Now you can access Swagger UI using public ip:3001 .

Conclusion:

Integrating Swagger with API Gateway is very easy since we only need to provide Host of Gateway and Path Prefix of Deployment. Also Swagger is very useful because it provides us nice UI and saves us using CURL commands.

If your goal is only to expose APIs for frontend developers or non-technical users then Swagger is recommended.

What’s Next:

I write blogs on Web Applications & CloudNative Approaches, You will find many interesting blogs here https://medium.com/@vgautam99

For future blogs, follow me here on Medium and I will appreciate claps on this blog.