Nov 1, 2021

Migrate Swagger to Serverless framework - CLI Tool (Rust)

I wrote the CLI tool that generates the Serverless framework project from the Swagger (OpenAPI specification) file in milliseconds. The goal was that tool must be fast and easy to use. Source code and the binaries are available as usual at the end of this article. It is written in Rust. License is MIT.

Usage:

slsswag path/to/swagger/file.yml platform` 
slsswag sample/swagger.yml nodejs
slsswag sample/swagger.yml csharp

Note: Currently works only with yaml. JSON is planned to be added later.

Sample folder contains petstore swagger file. When you execute the command, it will create the output folder with the complete project ready to be deployed. At the time of writing this article, the project is still under heavy development, but the NodeJS example works.

Motivation

The idea comes from several projects that I was migrating to serverless architecture using Serverless framework. API Gateway supports OpenAPI specification, but there is no good way to migrate it to Serverless. If you want to migrate an old project from Swagger, you must define all the endpoints by reading the specification, which is tedious and takes too much time. You are not limited to using this tool for migration. For example, using the slsswag tool unlocks the possibility of designing and documenting your API in Postman or Insomnia, exporting the specification, then using this program to scaffold your project.

Realization

Serverless framework on its own cannot add documentation to the API Gateway. For that purpose, we have to use the serverless documentation plugin. If you read one of my previous articles, you already know that I am learning Rust. Unfortunately, I don’t have too much time to dedicate to it, so I use every opportunity that I can take to practice. The need for this tool gave me a perfect excuse. Initially, I started playing around, and then I realized that it could actually work.

The program parses a swagger file and converts it into a format acceptable by the documentation plugin. For NodeJS it will generate:

  • Full serverless.yml with plugins, functions, and doc configuration
  • package.json
  • Function files with the code in it
  • Tests for the functions (Jest)
  • Documentation for each function file
  • Models

After running the command, you only need to execute npm install and your service is ready to be deployed.

  1. ./slsswag sample/swagger.yml nodejs
  2. cd output
  3. npm i
  4. sls deploy

One more important note is that API Gateway documentation does not support xml and example tags. Therefore you need to remove it from the generated docs, if any. Removing those tags is on the roadmap, but you have to do it on your own for now.

There are several items on my TODO list regarding code quality and improvements. Among other things, C# runtime is coming soon. Source code is available on GitHub. If you only need binaries to try, then you can find them here. Please use GitHub issues for any questions or comments.