A sample solution taking an API definition from SwaggerHub, crafting a Lambda function from the API definition, and then publishing the function behind AWS Gateway.
- Problem Statement
- Solution Overview
- Prerequisites
- Instructions
- Fork the repo
- Import the Book API into SwaggerHub
- Setup Auto Mock integration in SwaggerHub
- Test the Auto Mock integration
- IAM Role Setup for Deployment to AWS
- Deploy AWS API Gateway and AWS Lambda Function
- Update the SwaggerHub Books API with the AWS API Gateway endpoint
- Calling your AWS API Gateway hosted Books API from SwaggerHub
- Review the AWS API Gateway
- Continue the journey
API design tools and API gateways are two essential components in the development of modern API-based applications. Integrating these tools not only streamlines the API development process but also provides numerous benefits that enhance API functionality, security, and scalability.
SwaggerHub is a multi-spec API design and documentation tool that seamlessly integrates with Amazon Web Services. With this integration, you can establish a relationship between your design/development and your gateway/production environment. Having an integration between the design-time and the run-time allows you to push your API documentation directly from SwaggerHub into your gateway. Every time you update your document in SwaggerHub trigger the required processes to automate the journey towards the API management plane.
Managing your APIs from your gateway becomes a simpler task when you have your API documentation loaded into the tool automatically, there's no need to manually define how your APIs behave when SwaggerHub pushes your API definitions automatically.
By leveraging the seamless integration between SwaggerHub’s API design and documentation capabilities with AWS’s scalable and feature-rich gateway, organizations can confidently deliver innovative, customer-centric services and applications.
In this integrated exercise you will create an end-to-end solution which takes you through the process of creating an OpenAPI Specification (OAS) design definition, and deploying the API to an operational AWS environment.
- Import an existing OAS
Books APIdefinition into SwaggerHub SaaS design & documentation tool - Enable and test API auto-mocking on the newly imported API in SwaggerHub
- Build, test and deploy the following AWS resources/services:
- AWS Lambda Serverless Functions (a small backend microservice for the
Books API) - AWS API Gateway (to proxy API traffic to the implemented function)
- S3 bucket to store the release artifacts
- IAM roles needed to deploy and run the resources
- AWS Lambda Serverless Functions (a small backend microservice for the
- Update the SwaggerHub API to include the published AWS API Gateway endpoint
- Call the AWS API Gateway endpoints using SwaggerHub
- Review the AWS API Gateway (the setup of which is driven off the OAS definition)
- Learn about additional steps and functionality supported by the environment that has been setup
!!Solution Overview Image will go here!!
You will need an AWS subscription and a SwaggerHub account in order to be able to work on the API design, AWS Lambda implementation, and automated deployment to AWS API Gateway.
- Sign up for an AWS account (if required)
- Sign up for a SwaggerHub trial account (if required)
- Sign up for a GitHub account (if required)
The sample Lambda function generated within this repo uses dotnet6. If you would like to edit the code implementation, then the following are required:
- VS Code (or similar IDE)
- Install .NET 6.0
- Install Amazon Lambda Tools
dotnet tool install -g Amazon.Lambda.Tools
- Install SAM CLI (AWS Serverless Application Model Command Line Interface)
The instructions laid out below cover the following steps:
- Forking the repository for your local needs
- Importing the Book API into SwaggerHub
- Setup Auto Mock integration in SwaggerHub
- Test the Auto Mock integration
- IAM Role Setup for Deployment towards AWS
- Run GitHub Action to deploy AWS API Gateway and AWS Lambda Function
- Update the SwaggerHub Books API with the AWS API Gateway endpoint
- Calling your AWS API Gateway hosted Books API from SwaggerHub
OK - let's get started!
- Fork the repo to your local GitHub profile/organization
- Login into 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
- 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 dropdown, select API Auto Mocking and click the ADD button
- In the Name text box, enter
Auto Mocking - Click the CREATE AND EXECUTE button
- Click on the DONE button
- Click on the API name
book-apiagain to return to the editor view
Note that a new description and url tags have been added in the servers section of the API
- In the right panel, in the Servers dropdown, select the SwaggerHub API Auto Mocking server URL
- Open any of the Method/Path end-points (e.g.
GET /books) and click the Try it out button - Provide any
requiredparameters - Click the Execute button
- Review the data returned in the Server response box
In the next steps, we'll deploy a working version of the
books-apito AWS API Gateway and have a functioning Lambda function as the API implementation. Once deployed, we'll call the implemented API from SwaggerHub!
- Follow the IAM and Resource Setup Guide to ensure you can run the pipeline
- In your forked GitHub repository, navigate to the Actions tab
- Click on the
Pipelineaction on the left-hand pane - Run the
Pipelineworkflow 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
We'll need the API endpoint above to call the API, so keep it to hand!
- In the SwaggerHub Portal page, click on
Books APIto open the API definition - Locate the
serverstag, and replace theurlfor theAWS API Gateway Endpointserver tag (currently holding a value ofhttps://replace-me.com) with the value of the URL value copied from the pipeline summary above - Click the Save button
- In the SwaggerHub Portal page, click on
Books APIto open the API definition - In the SwaggerUI pane (the right-hand pane), choose the AWS API Gateway Endpoint from the Servers dropdown
- Expand
GET /books, click the Try it out button - Optionally, enter an
titleorauthorquery parameter - Click Execute
The Books API OpenAPI definition and the SAM Template combined drive much of the setup of the AWS API Gateway and linked Lambda Functions. The benefit of this is that the gateway will get automatically hydrated based on the design definitions.
Let's take a quick look
The API resources automatically configured in the gateway conform to the API definition (e.g. GET /books and GET /books/{id}).
The API models are automatically generated from the JSON Schema components contained in the API definition.
The API documentation is also generated from the API definition negating the need for documentation to be added after publishing to the gateway.
One of the major benefits of a gateway function is being able to observe how an API is being consumed. AWS API Gateway gives plenty of insights on API calls and performance out of the box.
TODO - this section will contain additional resources and hardening practices
- Using SwaggerHub Explore to interact with the surface area of an API
- Using the SwaggerHub CLI (command line interface) (LINK)
- Adding Custom Standardization rules and guidelines to SwaggerHub (LINK)
- User SwaggerHub Domains (share code libraries) to share common API components (LINK)
- Adding Authentication to the sample API and AWS Gateway (LINK)
- <> (LINK)