Access Swagger UI in AWS Lambda via API Gateway — Deployed with the Serverless Framework

Access Swagger UI endpoint for a .NET Core Web API hosted as an AWS Lambda with an API Gateway (Infrastructure As Code)

Swagger UI — What, Why and Who?

Well, why Swagger UI? Swagger UI gives users an interactive API documentation and lets you invoke the API very easily by using the web interface without having to gather what the endpoint, method, request headers, body parameters and so on actually are. You simply fill in the request parameters in the UI and off you go!— Invoke the UI!

If you weren’t using Swagger, then most likely you will have to contact the developers and ask them to give you the all the information on how to access the API and this can be really time consuming for both yourself and the developer. With Swagger UI this solves the problem as the developer could programmatically enable this functionality in code and keep the UI in sync with code changes so you don’t need to ask the developer each time the endpoint is updated.

Who would use Swagger UI — The QA’s, developers, stakeholders or simply any client who needs to consume or test your API.

Swagger UI Interface
Swagger UI Interface
A List of all Customer API endpoints that can be invoked via Swagger UI
Invoking the Create Customer endpoint via Swagger UI

Problem

There doesn’t seem to be many solutions for accessing Swagger UI running on an AWS Lambda via API Gateway. One of solutions which was fairly complicated required Amazon S3 where you would host the Swagger UI as static files. This was far too complicated for our use as it involved separately to sync the Swagger UI resources to the S3 Bucket and this required more effort and more development time when actually there was a simpler solution with far greater benefits and less effort!

What we needed was a much simpler solution — Simply documenting your C# code via XML comments and once the API has been deployed it would update the Swagger UI with the updated XML comments. Actually, this way was far more easier to implement than expected :)

To achieve this, we had to use Swashbuckle and Serverless Framework (Built on top of CloudFormation and makes it easier to deploy infrastructure code to AWS) — Please visit my Github page for the solution.

However, there is much simpler and easier solution involving Swashbuckle and API Gateway.

Technologies — What’s involved?

  • .NET Core 3.1 Web API (AWS Lambda)
  • REST API on API Gateway
  • AWS Serverless Framework (Abstraction layer in front on AWS CloudFormation — Makes it easier to write serverless application via infrastructure as code) — Creates the AWS Lambda Function and REST API in API Gateway. It also creates creates the endpoints on API Gateway so we can access the Swagger UI running in AWS Lambda.

Architecture

AWS Serverless Framework has been used to create the serverless applications.

An API Gateway has been created which forward requests to the Lambda Function. The key here for Swagger is: Lambda proxy integration is used to forward any Swagger UI requests to the Lambda.

API Architecture

Implementation

In this example we will create a .NET Core 3.1 Web API Application and create the Serverless Application using AWS Serverless Framework.

Swagger UI will be added to the .NET Core application using Swashbuckle. This is configured in the middleware of the application (Startup.cs) — see below.

This serverless file (infrastructure code) will create an API Gateway and a AWS Lambda. In the serverless file, we will setup a Lambda proxy integration in API Gateway which will forward any requests to the Swagger UI endpoint which lives in our Lambda allowing us to access Swagger UI.

There are two stages in implementing this solution:

  1. Create a new project in Visual Studio using the AWS Serverless Template. You will need to install Lambda Tools Extension for Visual Studio — You can do this via Nuget Package Manager extension. Or you can do this via Command Line if you are using Visual Studio on Mac OSX.
Visual Studio AWS Lambda Tools Extension Templates

2. Once the project has been created, install ‘Swashbuckle.AspNetCore’ Nuget package via Nuget Package Manager in Visual Studio.

This guide will explain how to use Swashbuckle in a fairly simple way to enable Swagger UI for your API. For more information on how to use Swashbuckle — please use the official Microsoft guide.

3. Edit your project (.csproj) file and enable XML comments for your project.

Set GenerateDocumentationFile to true into the PropertyGroup section. You can suppress warning for undocumented types — see Microsoft Guide.

<PropertyGroup>   <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

4. In the Startup.cs file you will need to add and configure Swagger middleware.

a. In the ConfigureServices(…) method, call the AddSwaggerGen method like below:

ConfigureServices method implementation in Startup.cs

b. In the Configure(..) method, call the UseSwagger and UseSwaggerUI methods.

When calling UseSwagger ensure you set the RouteTemplate path to ‘swagger/{documentName}/swagger.json’ as this will be the path where Swagger UI will be exposed.

Also, similar implementation applies for ‘useSwaggerUI ‘— We need to set the RoutePrefix to ‘swagger’ to reflect the Swagger endpoint.

ConfigureServices implementation in Startup.cs

5. Create a new controller. In this example we will create a Customer Controller which will have a GET and POST endpoint.

Add the XML comments to all the endpoints in the Customer Controller class. The parameters and response code types are declared for each method which is how Swagger UI interprets the information and displays this in UI form.

For example, for the GET method we have specified 200 and 500 response codes with an explanation of what the response codes mean. For more information on this, please see the Microsoft guide.

The CustomerController class is shown below.

6. Run project in Visual Studio and navigate to /swagger/index.html e.g. http://localhost:12946/swagger/index.html in this example.

Woohoo, you have Swagger UI running locally on your machine :)

Next steps, we need to get the API deployed onto AWS and access this via API Gateway. We will be using the Serverless Framework to deploy the API onto AWS.

In this stage, you will define all your serverless code in “serverless.yml” file. The serverless code will consist of creating the Lambda Function, API Gateway and implementing the Lambda Proxy integration for API Gateway that is required to access Swagger UI via API Gateway.

The customer resource endpoints have been defined in the serverless file — GET and POST. This will expose the endpoints in API Gateway and allow Swagger to invoke both endpoints.

Please note: API Gateway path is case sensitive so ensure your Route path in the Controller class matches the path defined in the serverless file (under http → path) otherwise you may have trouble invoking your API’s from Swagger UI.

functions:  
orders:
name: customers-lambda-${self:custom.stage}
handler: SwaggerAPILambda::SwaggerAPILambda.LambdaEntryPoint::FunctionHandlerAsync
environment:
ASPNETCORE_ENVIRONMENT: ${self:custom.stage}
events:
- http:
path: "api/customer"
method: "get"
cors: true
- http:
path: "api/customer"
method: "post"
cors: true
- http:
path: "swagger/{proxy+}"
method: "get"

Accessing Swagger UI via API Gateway — Setup Lambda Proxy Integration in API Gateway

In the serverless file, you will also see a proxy path defined for “swagger/{proxy+}” (shown below) which allows any GET requests that falls under the path ‘swagger/’ to pass through to the Lambda Function. Swagger UI is running on path: /swagger/index.html so API gateway will allow any GET requests made to this path to the Lambda Function.

- http:
path: "swagger/{proxy+}"
method: "get"

Please note: You will create to create an AWS S3 deployment bucket for your serverless code.

Deploying Serverless Application To AWS

We are building and deploying the application using Bitbucket Pipelines but you can do this with any pipeline of your choice e.g. CodePipelines. Please see the sample code as an example of how Bitbucket Pipelines are used to deploy serverless code.

Once it has been deployed you should be able to access it by:
https://{api-id}.execute-api.{region}.amazonaws.com/{stage}/swagger/index.html

For this example, this is the URL hosted on AWS: https://mlbej0yd24.execute-api.eu-west-1.amazonaws.com/beta/swagger/index.html

Swagger UI for AWS Lambda hosted on AWS

You can try invoking any endpoint using Swagger UI — Click on any endpoint and then “Try it out”.

Invoking the GET All Customer Details endpoint using Swagger UI

That’s it! You now have a Swagger UI endpoint which you can access via AWS API Gateway.

Sample Code

Please visit my Github repository for sample code.

References

Feel free to ask any questions or problems you may have :)

Shoutout to Ben Sloan for his advice on achieving this solution.

Software Developer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store