How to Streamline API Development on Amazon API Gateway Using SmartBear’s SwaggerHub

By Frank Kilcommins, API Technical Evangelist – SmartBear
By Micheál Higgins, Sr. Solutions Architect – SmartBear
By Matt Bonner, Sr. Marketplace Solutions Engineer – SmartBear
By Dan Fox, Principal Specialist Solutions Architect, Serverless – AWS

SmartBear

As the market for API products grows, so does the demand placed upon them by consumers. To meet these challenges, many Amazon Web Services (AWS) customers look to Amazon API Gateway as a solution for orchestrating the resources for creating, deploying, and managing APIs at scale.

Before an API can be deployed to a gateway, however, delivery teams face the more fundamental challenge of ensuring consistency and standardization for all stages of the API experience.

Large organizations often encounter this problem, especially when multiple teams are responsible for a portfolio of APIs. Those that fail to address this problem risk creating illogical and unpredictable API designs that can impact the consumption and adoption of the API.

Organizations can take a few practical steps to manage this problem across an extensive API network.

The first step is to document all APIs in a central location. There are two common methodologies for creating and documenting APIs: code-first and design-first.
- Teams that follow code-first methodology create application code first and then generate API documentation.
- Design-first practitioners do the opposite, creating the API documentation first and application code later.
- Both methodologies focus on building API documentation to help standardize end user API experience.
The second step is to ensure consistency of the documentation and implementation by applying governance patterns to APIs early in the design phase.

SmartBear’s SwaggerHub can help teams with both steps by providing a single source of truth for API documentation, as well as by supporting teams to achieve consistency in their documentation and implementation patterns across a portfolio of APIs. In this post, we show how SwaggerHub pairs with Amazon API Gateway to provide customers with a holistic API solution.

SmartBear is an AWS Partner that offers tools for collaborative development, functional testing, performance testing, and performance monitoring across APIs, mobile, and web.

Design-First and Code-First on Amazon API Gateway

API developers want to document, standardize, and publish their applications with maximum efficiency, regardless of whether their project follows a code-first or design-first approach.

If you write code first, you configure your API and logic within an API Gateway first. Later, you can publish your specification to SwaggerHub, which can perform OpenAPI specification validations to make sure your API is valid.

SwaggerHub can also perform custom validations and rules that you enable to help enforce any additional governance and guidelines you create. You can automate this process by exporting the API spec from the API Gateway using the AWS Command Line Interface (AWS CLI), and then by importing that spec into SwaggerHub using the SwaggerHub CLI.

If you follow a design-first methodology, you can use native integrations between Amazon API Gateway and SwaggerHub. The SwaggerHub API Gateway integration automatically pushes your API specification to API Gateway whenever you save it in SwaggerHub. This gives you the ability to quickly create or update an API in the API Gateway from SwaggerHub.

Meanwhile, the SwaggerHub Gateway Lambda Sync integration creates or updates API Gateway API’s that are backed by AWS Lambda.

Using these standard integrations, you can write and update API definitions in SwaggerHub and your APIs will automatically stay synchronized with API Gateway. As you enhance your API definitions in SwaggerHub, your changes and improvements are automatically pushed to your gateway. This process supports the DevOps principle of shifting left, enabling you to document, develop, and test in parallel.

Going from Design to Deployment

To understand the API delivery cycle, you can create an OpenAPI definition and put it into GitHub, which acts as the continuous deployment system. Changes in your source control repository trigger deployments to an API Gateway that proxies requests to a Lambda function. While this solution uses a design-first approach, it can be adopted to support code-first projects that generate API definitions from code.

To build this project you will take the following steps:

Import an existing API definition into SwaggerHub’s design and documentation tool and validate it against standards.
Enable and test API auto mocking on the newly imported API in SwaggerHub.
Build, test, and deploy the following AWS resources/services:
- AWS Lambda function (a small backend microservice for the Books API).
- Amazon API Gateway endpoint (to proxy API traffic to the implemented function).
- Amazon S3 bucket to store the release artifacts.
- AWS IAM roles needed to deploy and run the resources
Create a GitHub action that can be triggered to automate the process.
Update the SwaggerHub API to include the published Amazon API Gateway endpoint.
Call Amazon API Gateway endpoints using SwaggerHub.
Review Amazon API Gateway (the setup of which is driven off the OpenAPI definition).

You can find a working solution that uses SwaggerHub, Amazon API Gateway, and AWS Lambda in GitHub.

Figure 1 – Overview of the major architectural components.

Prerequisites

You need an AWS account, GitHub account, and SwaggerHub account to deploy this project.

To configure and execute the GitHub actions, fork the repository into your own GitHub profile/organization.

Import the Book API into SwaggerHub

Log in to SwaggerHub.
From the Create New menu, select Import and Document API.
Enter the following URL in the Path or URL input box:
- https://raw.githubusercontent.com/SmartBear-DevRel/SwaggerHub-AWSGateway-Lambda/main/API-Definition/openapi.yaml
Press the IMPORT button.
In the next pop-up window, click the IMPORT DEFINITION button.

You can leverage SwaggerHub’s collaboration and standardization capabilities to ensure your API documentation meets the needs of your consumers. Check out how SwaggerHub helps achieve API design excellence.

Set Up Auto Mock Integration in SwaggerHub

In the SwaggerHub Portal page, click on the Books API.
In the left pane, click on the API name books-api.
Click on the Integrations tab.
Click on Add New Integrations.
In the Integrations drop-down, select API Auto Mocking and click the ADD button.
In the Name text box, enter Auto Mocking.
Click the CREATE AND EXECUTE button.
Click the DONE button.
Click on the API name book-api again to return to the editor view.

Note that a new description and URL tags have been added in the servers section of the API.

Test the Auto Mock Integration

Next, set up auto mocking within SwaggerHub to allow consumers and interested stakeholders to quickly interact with the API design.

In the right panel, in the Servers drop-down, select the SwaggerHub API Auto Mocking server URL.
Open any of the Method/Path endpoints (for example, GET /books) and click the Try it out button.
Provide any required parameters.
Click the Execute button.
Review the data returned in the Server response box.

In the following steps, you will deploy a working version of the books-api to Amazon API Gateway and AWS Lambda. Once deployed, we’ll call the API from SwaggerHub.

Deploy Amazon API Gateway and AWS Lambda Function

Follow the IAM and Resource Setup Guide to ensure you can run the pipeline.

You can use GitHub actions to deploy AWS resources and publish code, documentation, and definitions to Amazon API Gateway.

In your forked GitHub repository, navigate to the Actions tab.
Click on the Pipeline action on the left-hand pane.
Run the Pipeline workflow by clicking on the Run workflow button.
Once the pipeline has completed, navigate to the bottom of the pipeline summary and locate the output-endpoint summary section.
Copy the AWS_API_Gateway_Endpoint URL and save it somewhere. You’ll need this later to call the API.

Update the SwaggerHub Books API

In the SwaggerHub Portal page, click on Books API to open the API definition.
Locate the servers tag, and replace the URL for the Amazon API Gateway endpoint server tag (currently holding a value of https://example.com/) with the value of the URL value copied from the pipeline summary above.
Click the SAVE button.

Call the Amazon API Gateway Hosted Books API from SwaggerHub

In the SwaggerHub Portal page, click on Books API to open the API definition.
In the SwaggerUI pane on the right, choose the Amazon API Gateway endpoint from the Servers drop-down.
Expand GET /books, and click the Try it out button.
Optionally, enter a title or author query parameter.
Click Execute.

Review the API Gateway Configuration

The Books API OpenAPI definition and SAM Template contain the configurations for Amazon API Gateway and the linked Lambda function. The benefit of using this approach is that your gateway will get automatically hydrated by design definitions, saving you manual work post deployment.

Created Resources

The following API resources automatically configured in the gateway conform to the API definition (for example, GET /books and GET /books/{id}).

Figure 2 – API Gateway resources created by SwaggerHub.

The API models are automatically generated from the JSON Schema components contained in the API definition.

Figure 3 – API data model generated by SwaggerHub.

The API documentation is also generated from the API definition, negating the need for documentation to be added after publishing to the gateway.

Figure 4 – API documentation created by SwaggerHub.

You can direct users to the SwaggerHub to view API consumer documentation.

Figure 5 – API documentation in SwaggerHub.

You can also observe how your API is being consumed. Amazon API Gateway gives insights into API calls and performance out of the box.

Figure 6 – API Gateway dashboard.

Cleanup

To delete the resources created and avoid recurring costs, follow these steps:

Open the AWS Management Console and delete the created AWS CloudFormation stack (books-api-dev). It will delete the created API in Amazon API Gateway and the AWS Lambda functions.
Delete three IAM roles: books-api-dev-bookstorefunction, aws-actions-dev-CloudFormationExecutionRole, and aws-actions-dev-PipelineExecutionRole.
Clean up the Amazon S3 bucket with the code artifacts for deployment. Empty the contents of the bucket, and then delete it.
Delete the API in the SwaggerHub.
Delete pipeline action in GitHub Actions.

Conclusion

You can combine SwaggerHub and Amazon API Gateway to provide standardized API experiences for your end users. SwaggerHub serves as a central hub for API design, documentation, and collaboration, while Amazon API Gateway serves as an API management proxy in front of your implementation.

Regardless of whether you employ a code-first or design-first approach, you can automate your process to ensure a consistent experience across the API definition, implementation, and deployment processes. This gives you additional confidence and tooling when developing API products for your end users.

Resources:

Use SwaggerHub Explore to interact with the surface area of an API.
Use the SwaggerHub CLI.
Add custom standardization rules and guidelines to SwaggerHub.
Use SwaggerHub domains (shared code libraries) to share common API components across multiple APIs.
Add authentication to the sample API and Amazon API Gateway.

.

.

SmartBear – AWS Partner Spotlight

SmartBear is an AWS Partner that offers tools for collaborative development, functional testing, performance testing, and performance monitoring across APIs, mobile, and web.

Contact SmartBear | Partner Overview