Swagger UI for AWS API Gateway Endpoints

Swagger UI

During the course of developing and consuming APIs, developers face many problems like,

• Going through the API documentation.
• Having knowledge of request parameters.
• Knowing the response models.

As the number of APIs increases, the complexity of the above said problems increases. However, this can be resolved by using Swagger UI.

Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place.

But AWS API Gateway doesn’t give any kind of endpoint to integrate with Swagger. It needs some kind of tweaks to integrate it.

At Nggawe Nirman we had a similar problem to solve. In this post we will look at how to setup swagger on S3, integrate it with API Gateway and see how we overcame this problem.

The major reason to host swagger on S3 is we can host static websites on S3 for one to two dollars a month and scale to handle millions of users.

Prerequisites

Below are the pre-requisites in order to set up a swagger on S3.

• You should have read and write access to the below AWS S3.
• Additionally, you should have awscli installed and configured in your machine.

Setting up S3 Bucket for Static Hosting

• Navigate to S3 in AWS console and create a bucket with some name like swagger-bucket.
• Under the properties tab, enable Static website hosting and make a note of the link provided.
• In the Index Document, enter the name of the document as index.html.
• Under the permissions tab, select bucket-policy and update the policy document using the below content. Replace the bucket name with the actual one.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::<Bucket Name>/*"
            ]
        }
    ]
}

Please follow this guide for detailed steps.

Note: This post assumes that the below setup would be carried out on either a Linux/mac os.

Publishing Swagger Code on S3

• From the swagger-ui releases page download the latest package and untar it.

wget https://github.com/swagger-api/swagger-ui/archive/v3.24.3.tar.gz
tar -zxvf v3.24.3.tar.gz

• Go to dist folder and copy them to the above created S3 bucket.

cd swagger-ui-3.24.3/dist/
aws s3 sync . s3://<Bucket Name>/

• Open the previously noted link in the browser and you should be able to view the swagger-ui something like this.

Swagger-Page

Visualizing your AWS API Gateway Endpoints

• Create a shell script get-docs.sh inside the dist folder and paste this content in it.
• Run the newly created script. This script creates a folder named docs and copies all the AWS API Gateway documents with this format {Stage}-{API-Gateway}.json inside docs folder.

bash get-docs.sh

• A docs-list.json file will be with the below data format.

[
  {
    "url": "file-path/url-link",
    "name": "name-to-display"
  }
]

• Inside the dist folder, replace the content of the index.html with this. This will help you create a drop-down like a menu for selecting all of your AWS API Gateway documents by importing docs-list.json.
• Now sync the bucket with the latest changes in order to view the endpoints.

aws s3 sync . s3://<Bucket Name>/

• You will now be able to see your API Gateway Documents in the form of drop-down menu as shown below.

Swagger with API Gateway Documents.

Capturing the latest changes and adding new APIs

• In order to update the latest changes and capture the addition of new API’s, run the get-docs.sh either as a part of the Lambda Deployment or as a Cron Job.
• The script should be something similar to the one mentioned below.

aws s3 sync s3://<Bucket Name>/ .
bash get-docs.sh
aws s3 sync . s3://<Bucket Name>/

For other API endpoints that support Open API Document

• In order to view the other API documents, place the document in the docs folder, and update the docs-list.json file with the relative file path of the copied document.

[
  ...
  ...
  {
    "url": "file-path",
    "name": "name-to-display"
  }
]

• If your API supports swagger endpoint, then you can directly view them without exporting the document by creating a new element in the docs-list.json something similar to this.

[
  ...
  ...
 {
    "url": "api-url",
    "name": "name-to-display"
  }
]

Conclusion

With this setup, you would need not specifically remember your API endpoints and struggle with them. Rather you can come here, select the required API, see the document, know the parameter required, test it and see the response model and use the same in your development.

Thank you Karthikeyandon for helping in this Setup.

Thank you for reading and keep following Nirman-Tech to see more such posts.

The END