Creating Swagger + API Gateway Extensions with ‘api-to-cloud’
Introduction
For one of the projects, I had to develop a REST API. It hat to be a public API with several GET and POST endpoints. Nothing crazy. After a short research, I chose Swagger as a development and documentation tool.
Within couple days I described API endpoints and data models in swagger. The file was provided to the consumers of the API. And I started work at API stubs so that users could test integration.
For stubbing, I chose AWS API Gateway backed by AWS Lambda. It is possible to provide the swagger file as a template for API Gateway. And AWS will create API endpoints for you. But the devil is in the details.
Problem
First, AWS does not support some of the swagger’s features. By trial and error I found the following unsupported fields:
- example field in the model definition
- responses.default field in the path definition
I tried to create API Gateway from a simple swagger file. And here you can see what I’ve got:
As you can see the error messages are not very informative.
Secondly, AWS adds custom extensions to swagger to describe various backend integrations. API Gateway cannot be created from the swagger file without these extensions.
So, if you want to share an API documentation, for instance via swagger-ui, you would need to support at least two files:
- file with all swagger features for documentation purposes
- file with AWS specific extensions to describe integrations
But API should be provider agnostic, shouldn’t it?
Solution
After a short brainstorm I came up with an idea to separate API description into two parts:
- pure API in swagger format with all features
- extensions specific to cloud providers
These two parts are completely independent. So, it became possible to design a tool which can generate cloud-specific API description at runtime.
As you can see the tool consumes two files: swagger file and extensions file. The result of the processing is the full API definition for a specific cloud provider. And original swagger file can still be used for documentation and development purposes.
Installation and usage
api-to-cloud is a NodeJS module available through the npm register.
Installation is done using the ‘npm install’ command:
$ npm install @antklim/api-to-cloudapi-to-cloud can be used in two ways: as CLI tool and as a programmatic library. CLI extension allows it to be used in the CI/CD pipelines. Please, refer documentation for more usage information.
The Future
That’s all for today. It may look too simple and be lacking for the features. But I’ve just begun development. The next planned feature is to add support for Microsoft Azure API Management. Or leave your comments about features you would like to see in the tool. Also, code contributors are always welcome!
Make sure to follow with the GitHub repo for updates. Thanks!
