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:

swaggerDoc1

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!

Back to Posts