Cdk-apigateway-swagger-ui

10 min read Oct 09, 2024

Leveraging Swagger UI with AWS CDK for Your API Gateway

Developing and managing APIs can be a challenging task, especially when you're dealing with complex functionalities and a variety of endpoints. To streamline the process, it's crucial to have a robust documentation system that allows developers to easily understand and interact with your API. Enter Swagger UI, a powerful tool that provides an interactive interface for visualizing and testing your API documentation.

But how do you integrate Swagger UI with your AWS infrastructure? That's where the AWS CDK (Cloud Development Kit) comes in. CDK empowers you to define your cloud infrastructure as code, making it easier to manage, deploy, and update your resources.

In this article, we'll explore how to utilize the CDK to seamlessly integrate Swagger UI with your API Gateway, making API documentation a breeze.

Why Use Swagger UI with AWS CDK?

Centralized Documentation: Swagger UI provides a single, interactive platform to access all your API documentation, reducing the need for scattered documents and confusion.
Improved Developer Experience: With interactive documentation, developers can easily understand your API structure, test endpoints with various parameters, and quickly identify potential issues.
Enhanced Collaboration: Shared Swagger UI documentation fosters better communication between developers and other stakeholders, promoting collaboration and ensuring everyone is on the same page.
Automated Deployment: Using CDK, you can automate the deployment of your API Gateway and Swagger UI infrastructure, making the process faster and more reliable.

Setting Up the CDK Environment

Before diving into the integration, ensure you have the following prerequisites:

AWS Account: You'll need an AWS account to deploy resources.
CDK CLI: Install the CDK command-line interface for managing your CDK projects.
Node.js and npm: The CDK relies on Node.js and its package manager, npm.

Creating a CDK Project

Initiate a new CDK project:

cdk init app --language typescript

Install necessary dependencies:

npm install @aws-cdk/aws-apigateway @aws-cdk/aws-s3 @aws-cdk/aws-s3-deployment aws-cdk-lib @types/aws-lambda aws-sdk

Defining your API Gateway

Let's create a simple REST API using the CDK:

import * as cdk from 'aws-cdk-lib';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as s3Deployment from 'aws-cdk-lib/aws-s3-deployment';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import { Construct } from 'constructs';

export class CdkApigatewaySwaggerUiStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Create a new API Gateway REST API
    const api = new apigateway.RestApi(this, 'MyAPI', {
      restApiName: 'MyAPIGateway',
      description: 'A simple API to demonstrate Swagger UI integration',
    });

    // Create a Lambda function to handle API requests
    const lambdaFunction = new lambda.Function(this, 'MyLambdaFunction', {
      runtime: lambda.Runtime.NODEJS_16_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
    });

    // Integrate the Lambda function with the API Gateway
    const integration = new apigateway.LambdaIntegration(lambdaFunction);

    // Add a GET endpoint to the API
    api.root.addResource('hello').addMethod('GET', integration);

    // Create an S3 bucket to store Swagger UI files
    const swaggerUiBucket = new s3.Bucket(this, 'SwaggerUiBucket');

    // Deploy Swagger UI files to the S3 bucket
    new s3Deployment.BucketDeployment(this, 'SwaggerUiDeployment', {
      sources: [s3Deployment.Source.asset('./swagger-ui')],
      destinationBucket: swaggerUiBucket,
    });

    // Create an API Gateway deployment
    const deployment = new apigateway.Deployment(this, 'Deployment', {
      api,
    });

    // Create an API Gateway stage
    const stage = new apigateway.Stage(this, 'Stage', {
      deployment,
      stageName: 'prod',
    });

    // Configure API Gateway to use Swagger UI for documentation
    const swaggerUrl = `https://${swaggerUiBucket.bucketWebsiteDomainName}/index.html?url=${stage.url}/swagger.json`;
    cdk.Tags.of(swaggerUiBucket).add('SwaggerUI', 'true');
    cdk.Tags.of(stage).add('SwaggerUI', 'true');

    // Log the Swagger UI URL
    console.log(`Swagger UI URL: ${swaggerUrl}`);
  }
}

Explanation:

API Gateway: We create a simple API Gateway REST API using apigateway.RestApi.
Lambda Function: A Lambda function is created to handle API requests (lambda.Function).
Integration: We integrate the Lambda function with the API Gateway using apigateway.LambdaIntegration.
Endpoint: We add a basic GET endpoint to the API with a path of hello using addResource() and addMethod().
S3 Bucket: An S3 bucket is created to store Swagger UI files (s3.Bucket).
S3 Deployment: The Swagger UI files are deployed to the S3 bucket using s3Deployment.BucketDeployment.
Deployment and Stage: We deploy the API Gateway using apigateway.Deployment and create a stage called "prod" using apigateway.Stage.
Swagger UI Configuration: The API Gateway is configured to use Swagger UI for documentation by providing the URL of the Swagger UI files in the S3 bucket.
Tags: We add tags to the S3 bucket and stage for easier identification.

Generate Swagger Documentation

Before deploying, generate the Swagger documentation for your API:

Use tools like OpenAPI Generator or Swagger Editor to create a swagger.json file based on your API's structure. This file will describe your API endpoints, parameters, and responses.

Deploying your Infrastructure

Synthesize your CDK application:

cdk synth

Deploy your CDK stack:

cdk deploy

Accessing Your API Documentation

After deploying your CDK stack, the generated Swagger UI URL will be printed to the console. Open this URL in your browser, and you will be presented with an interactive interface that allows you to explore your API documentation, test endpoints, and much more.

Customization

You can customize your Swagger UI installation by editing the swagger-ui folder. Add custom CSS, Javascript, or additional documentation files to suit your needs.

Conclusion

By leveraging the power of the AWS CDK and Swagger UI, you can significantly simplify your API documentation process. This approach offers numerous benefits:

Improved Developer Experience: Developers gain a unified platform for exploring your API.
Enhanced Collaboration: Sharing the Swagger UI documentation promotes better collaboration.
Automated Deployment: CDK automates the infrastructure setup and deployment, ensuring consistency and reliability.

Integrating Swagger UI with your API Gateway using CDK is a powerful way to create a seamless and well-documented API experience. As your API evolves, this approach remains flexible and easily scalable.