Today I read the announcement of OpenAPI (fka Swagger) support in API Gateway on OCI. I was wondering what that entailed and I decided to try it out.
In short, this support means that an API definition can be uploaded to API Gateway, is validated for correctness and can be shared among people accessing the OCI API Gateway definition on OCI. Furthermore, an API Deployment can be created from the imported OpenAPI definition, with routes (of type Stock Response) for the paths in OpenAPI definition. I will demonstrate this in this article.
Robert Wunderlich in his announcement wrote:
- Faster prototyping: A stock response API can be automatically created for developers and their consumers to test the APIs ahead of the implementation. A developer can add policy configurations around the stock response for deeper prototyping.
I have not seen this automated creation of the actual stock response content. I am not sure if that is what he means, but that certainly would be nice. The documentation on this specific feature is pretty limited.
So let’s quickly get going, with the simplest of OpenAPI definitions:
I copied and pasted the definition to a file called open-api-3-0-simple.yaml.
Then I opened the OCI Console and went to the API Gateway menu entry.
On this page I clicked on APIs and on Create API Resource. I typed the name simple-api and up0loaded the very simple API definition.
I pressed Create. The OpenAPI definition is validated
and the API Resource is created from it.
Soon, validation is done.
The API Description can be inspected – by me and I will just see the contents of the file I just uploaded but also by my colleagues:
I switch to API Deployment Specification and click on Deploy:
This instructs API Gateway to create an API Deployment based on this API definition.
The API Deployment wizard appears. I have to select the Gateway to create the deployment on:
and I need to provide a name and a base path.
Then press Next. For each path in the API definition, a Route is defined in the API Deployment for me. In this case that happens to be just a single route. The elements in the red rectangles are predefined – based on the OpenAPI definition.
I have to make up the body of the stock response myself. Or I can use https://app.swaggerhub.com/ to edit my OpenAPI definition, add a model and get the stock response generated and copy and paste it into the route definition.
Or better yet, go to https://app.swaggerhub.com/search to find a more interesting API to work with – because this simple api is a tat too simple.
Click Next,
Confirm the definition and press Create to roll out this API Deployment to the live API Gateway.
It will take a little while for this deployment to be live.
In the mean time, I copy the URL Endpoint for the API Deployment.
Then in Postman, I paste the endpoint, add /list for the specific Route (or OpenAPI Path) I want to invoke and make the call:
As expected (or at least hoped for) I get the stock response I expected.
Of course this OpenAPI definition was really too simple to prove anything. However, I could very easily include the OpenAPI definition in API Gateway and make it accessible to my project team members. Creating a mock implementation for this API with (handcrafted) mock responses is fairly straightforward.
This feature is not the silver bullet, but it is a nice addition to API Gateway. And it seems an indicator of where API Gateway is going.
Resources
OCI API Gateway Documentation on OpenAPI support
Announcement of OpenAPI Support on API Gateway:https://blogs.oracle.com/cloud-infrastructure/announcing-openapi-support-in-api-gateway
