Serverless Auto-Swagger Plugin Release
Do you want to have your API documented but hate having to manually change it every time there is an API change?
Find that the actual API and the documentation drift apart?
This is exactly what I found so I created this plugin to solve that issue.
We also have a video version of this tutorial if you prefer!

What the plugin does
This plugin is designed to make having a Swagger UI as simple as possible. It uses your existing Serverless Framework API configuration with your typescript types to generate a swagger.json file.
It then adds a {your-api-url}/swagger
endpoint where your custom swagger UI is hosted.
How to use the plugin
Using this plugin is super simple. At the initial level all you need to do is install the plugin and add it to your plugin list.
npm i -D serverless-auto-swagger
plugins:
- serverless-auto-swagger
Now when you run sls deploy
the serverless plugin will generate your swagger.json file and add the new endpoints for the swagger UI.

If you're using TypeScript
If you're using a serverless.ts project with webpack then there is one extra steo that you currently need to make. In your tsconfig.json
you need to add '.js'
to your resolve extensions.
resolve: {
extensions: ['.mjs','.json','.ts','.js'] ...
}
We hope to release an update soon which will remove this extra step for TypeScript users.
Further Customisation
Once you've got the initial version of your swagger working it's time to start making it more complete. The first thing is adding some responses to your endpoints.
In your serverless config, when you define your Lambda http
events, you can now add some extra fields. You can define which responses the API should return with some simple syntax. Adding a responses
section to your http
config will allow you to define the possible responses a user could get from the API. In this example, we add a 200 and 400 response code.
http: { method: 'get', path: 'flights', responses: { 200:{ description: 'successful API Response', }, 400:{ description: 'failed API Response - user error', } } }
Adding Types
Now that we can add response codes to our documentation, we might want to tell the user what response object they're expecting.
We can do this really easily by utilising our existing typescript types. If we have a type of getFlightsResponse
we can simply add that as the bodyType
for our 200 response.
http: { method: 'get', path: 'flights', responses: { 200:{ description: 'successful API Response', bodyType: 'getFlightsResponse' }, 400:{ description: 'failed API Response - user error', } } }
We just need to make sure that we are exporting the getFlightReponse
from a file called src/types/api-types.d.ts
.
We could also add some config to our custom section of our serverless config to redirect the serverless auto-swagger. It just needs to be an array of typescript files that contain the interfaces we want to use in our swagger documentation. In our case we have all of our types in our flights.d.ts
file.
custom: { autoswagger: { typefiles: ['./src/types/flights.d.ts'], }, ... }
This results in documentation like this:
Adding Post Types
So we know how to add types to a get request, but what about a post or put request. Things actually work almost identically. All you need to do is add a bodyType: 'myType'
to the main section of your event config.
http: { method: 'post', path: 'flights/{flightID}', bodyType: 'PostFlightBody', },
This will work exactly as the response bodyType
does. If you need to add a new file to the autoswagger typefiles list then do that now.
When you next run sls offline start
or deploy the API you'll have documentation for what the user needs to send to your API!