If you’ve got a Serverless API deployed to AWS API Gateway and it’s not documented with Swagger spec, you’re missing out. Having a Swagger specification for your REST API opens up some great opportunities, in addition to having great documentation for your API in a standard format.
AWS API Gateway has some powerful features around Swagger, allowing you to import and export your APIs in the format. We’ll be using it to export a valid Swagger specification for our example API which we can then use to build a mobile app in Dropsource. To do this, we’ll be using the “serverless-aws-documentation” Serverless Framework plugin, writing some YML markup to describe our endpoints and models, and then letting the API Gateway’s documentation feature take care of the rest.
To keep things simple, let’s use an example API provided by the Serverless Framework project for demonstration purposes. If you’ve already got an API with the Serverless Framework installed, you can skip to step #4.
- Follow the Serverless getting-started guide to install Serverless on your machine and configure your AWS account: https://serverless.com/framework/docs/getting-started. Complete the pre-requisites portion of the guide (including setting up your AWS credentials) and stop before ‘creating a new service’, as we’ll be using an example.
- Grab a copy of the example todo api (sans Swagger documentation) from the Dropsource Github. Just click the green “Clone or download” button and download the project files as a ZIP. Note: this project is just a copy of one of the official Serverless example projects. Also, the code for this completed how-to can be found here but we suggest following the rest of the steps to get things right.
- Follow the instructions in the example API README to setup and deploy it to AWS. After deploying you should be able to visit your API Gateway dashboard in AWS and see your new API. Click on it, and navigate to “Stages”, then select the “dev” stage, and you’ll see the url you should use to invoke it in blue at the top, it should look like: “https://xxxxxxxx.execute-api.us-east-1.amazonaws.com/dev” You can try creating, listing, updating, and deleting todos with curl or a tool like Postman. Instructions on parameters to send and expected responses can be found in the same README. You can also browse the “todos” DynamoDB table in AWS to view todo items you create by calling the API.
- Next, we’ll install the serverless-aws-documentation plugin for Serverless. Instructions can be found in the README. If you’re not familiar with Swagger spec, it may be worth getting to know it (especially if you’re documenting your own API), but you should be able to follow our example without too much expertise.
Documenting Your Models and Endpoints
Because we’re just writing markup, it’s easy to manage and version alongside your code and configurations. The serverless-aws-documentation plugin will let us add markup to the serverless.yml file in our project, and have that deploy to API Gateway when we deploy the API. It should be noted that we’ll be writing some markup that’s similar to Swagger in the configuration file, but it’s more just something that API Gateway will be able to turn into a fully-valid Swagger file for us when we’re ready to export.
The plugin README has good usage examples which cover everything you need to know, but the changes we’ll be making are obvious in the commit diff found in the completed code repository for this how-to. They consist of two major parts: the models and endpoints. Start by creating a “custom” section in your serverless.yml. In it, we’ll create the “documentation” section, which describes some general information, as well as the models themselves. After that, we can make use of those models in describing our endpoints.
Your serverless.yml file should look like this after you’ve documented your models and endpoints.
You should have already added the serverless-aws-documentation plugin to your package.json during step #4 of “Installation” above, but make sure your package.json looks like the snippet below and that you’ve run the
npm install command to install the plugin.
"description": "Serverless CRUD service exposing a REST HTTP interface",
Again, the complete code for this example can be found on the Dropsource Github.
This is a good time to mention that while this example API provided with the Serverless framework is enough to get us started and demonstrate the power of a well documented API, there are a few potential improvements you’d want to consider when creating your own API. The most glaring of which is better of use of status codes and error responses. For example, querying for a todo that doesn’t exist should return a 404 http status code, and be documented in the Swagger as such, instead of the 200 success code returned the current implementation. Another obvious one is authentication/authorization and monitoring. Most API’s will need a way to allow and deny access, as well as handle things like rate limiting. All of these are possible with the Serverless Framework on AWS, and arguably a lot easier than traditional methods. We do get logging to AWS Cloudfront out of the box, and you can use that to add further logging where appropriate.
Deploying and Exporting The Documentation
Once you’ve made your changes to the serverless.yml file, a simple
serverless deploy in your project directory will create the corresponding documentation parts in API Gateway and make it ready for export. You can now do that by clicking on ‘stages’ for your API, click the ‘dev’ stage (or any stage you may already have set up), and opening the ‘export’ tab. You’ll see options to export as Swagger .json or .yml. For now, use the JSON option and download the Swagger spec.
Using your API in Dropsource
Now that we’ve documented our API, we can use it to start building a mobile app in Dropsource, or any number of other things. Swagger is also an excellent format for other developers when they want to use your API in the things they’re building, or to just host the documentation as a web page with Swagger UI.
If you don’t have a Dropsource account yet, you can easily sign up for a free account by clicking here. After creating your account, create a new project (we’ll be using iOS, but you can do the same thing in Android with Dropsource). The Dropsource Help Center has solid documentation on how to use Swagger to build an app powered by an API, and you should check that out for full understanding of all the powerful features it enables, but in the meantime here’s a video of how easy it is to use this example API in an app that will create todo items, and then list them for us.
Try adding more functionality to the app we’ve built to support updating and deletion of todos! Remember, the Dropsource Help Center has lots of helpful how-tos to get you started. And if you need further assistance building your app, you can always get a hold of us using the chat bubble inside of Dropsource.