Amazon API Gateway Lambda Sync

AWS Lambda is Amazon’s compute service that lets you run code in response to HTTP requests. AWS Lambda along with Amazon API Gateway allow you to implement serverless REST APIs on the AWS platform. To do this, you configure your REST API in Amazon API Gateway and map individual API operations, such as POST /pet, to specific Lambda functions executed with Node.js or Python. The Lambda function runs whatever logic is needed to process the request. The result of the Lambda function is then returned by API Gateway to the caller.

SwaggerHub’s Amazon Lambda Sync integration allows you to create or update Lambda-based APIs in API Gateway from SwaggerHub. Your API definition is pushed to API Gateway every time you save it in SwaggerHub. This way, you can write and update your API definitions in SwaggerHub and automatically keep them synchronized with API Gateway.

Video tutorial


Difference between API Gateway integration and Lambda Sync

The difference is in the back end type you use for your API. If you have an existing API server and you want to proxy or secure via API Gateway, you should use Amazon API Gateway Integration. That integration creates or updates API Gateway APIs that work in the HTTP Proxy mode. Lambda Sync is for API Gateway APIs that use Lambda functions as the back end.

Supported OpenAPI versions

Lambda Sync supports both OpenAPI 2.0 and OpenAPI 3.0. SwaggerHub On-Premise users need v. 1.27 or later to use OpenAPI 3.0 definitions with this integration.


While Amazon API Gateway supports most of the OpenAPI 2.0 and 3.0 Specifications, it does not support some features (such as discriminator). See the known limitations below, and make sure your API definition uses only the features supported by Amazon API Gateway.

How Lambda Sync works

SwaggerHub matches and creates Lambda functions in Node.js or Python by using the operationId property of each API operation:

      operationId: addPet
      description: Add a new pet to the store

If an operation does not have the operationId property (it is optional), it will be created for you. If a Lambda function already exists with the same name as the operationId, the existing function will be used (no new function will be created).

You an also add API Gateway-specific information to your OpenAPI definition by using API Gateway extensions. For example:

        type: "aws"
        uri: "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:addPet/invocations"
        passthroughBehavior: "when_no_match"
        httpMethod: "GET"
            statusCode: "200"
          body: "$input.body"
          application/json: "{\n  \"body\" : \"$input.body\"\n}"


  • Lambda Sync is one-way, which means your API definitions go from SwaggerHub to API Gateway, but not vice versa. You should edit your API definitions in SwaggerHub only.

  • Like other SwaggerHub integrations, Lambda Sync is tied to a specific version of an API. If your API has multiple versions, you can configure Lambda Sync separately for different versions.

Step 1. Configure access to Amazon API Gateway

To be able to deploy to API Gateway, SwaggerHub needs access to AWS and a secret key with the appropriate permissions:

  1. Sign in to the Amazon AWS console at

  2. In the top right corner, under your username, click My Security Credentials.

    Security Credentials

    If you do not see the My Security Credentials menu, then click Services in the AWS header, type iam into the search bar, and click IAM in the search results.

  3. If a prompt appears, select Continue to Security Credentials.

  4. On the left, select Users and click Add user.

    Create New Users
  5. Enter the user name, for example, SwaggerHubUser. For the Access type, select Programmatic access.

    Creating a user

    Click the image to enlarge it.

  6. Click Next: Permissions.

  7. Select Attach existing policies directly and select the check boxes next to the following policies:

    • AmazonAPIGatewayAdministrator

    • AWSLambdaFullAccess

  8. Click Next: Review, then Create user.

  9. Important: Note down the Access key ID and Secret access key – this is the only time you see them. You will need to specify these keys in SwaggerHub.

    Access Key ID and Secret Access Key


Step 2. Create an execution role for Lambda functions

Each Lambda function has an execution role that gives it permissions to access other AWS services, such as S3, VPC or DynamoDB. Roles are created and managed in the IAM section of the AWS console. If you do not have a role for Lambda functions yet, you need to create one.

To create a role:

  1. In the IAM console, select Roles on the left.

  2. Click Create role.

    Creating a new role
  3. Select AWS service as the entity type and select Lambda in the list of services.

    Creating a role for the Lambda service

    Click the image to enlarge it.

  4. Click Next: Permissions.

  5. Select the check boxes next to the required permission policies. In this tutorial, we will use AWSLambdaBasicExecutionRole, which is the minimum permission required by Lambda functions. In a real-world scenario, you will have to add the necessary permissions to access AWS services that your Lambda functions will call.


    You can add permissions to or remove them from roles at any time later.

    Attaching permission policies to the role

    Click the image to enlarge it.

  6. Click Next: Tags.

  7. (Optional) Add tags if you want to.

  8. Click Next: Review.

  9. Enter a name and an optional description for the role.

    Role name and description

    Click the image to enlarge it.

  10. Click Create role.

  11. Click the created role.

  12. Note down the Role ARN. You will need to specify this value in SwaggerHub.

    Role ARN

    Click the image to enlarge it.

Step 3. Configure Lambda Sync

  1. Open your API page in SwaggerHub.

  2. If the API has several versions, select the version you want to push to Amazon API Gateway.

    Selecting an API version
  3. If this version is published, unpublish it. Only unpublished APIs can be integrated with Amazon API Gateway.

  4. Make sure the API definition meets AWS requirements (see above).

  5. Click the API name, switch to the Integrations tab, and click Add New Integrations:

    Add New Integration menu command
  6. Select Amazon API Gateway Lambda Sync from the list of integrations.

  7. Enter integration parameters:

    • Name – A display name for this integration, for example, aws lambda sync.

    • AWS Region – Select the AWS region where you want to publish your API or that contains the existing API you want to publish to.

    • API ID – Leave it blank to create a new API in API Gateway. Alternatively, if you want to update an existing API in API Gateway, specify the API ID here or in the x-aws-api-id key at the root level of your API definition.


      You can find API IDs on the APIs dashboard in the API Gateway console.

      API IDs in Amazon API Gateway

      Click the image to enlarge it.

    • Publish Mode – Choose how to handle existing APIs in API Gateway:

      • merge –Merge changes: add new changes made in SwaggerHub to API Gateway. This can be useful, for example, if your API in API Gateway is split into multiple parts in SwaggerHub, and you want only to synchronize the changes in one of these parts. The items that exist in API Gateway but are not defined in SwaggerHub will not be changed.

      • overwrite – (Recommended) Overwrite the existing API in API Gateway with the definition from SwaggerHub.

    • Base Path Mode – Choose how API Gateway should interpret the basePath property of your API definition. The options are ignore, prepend or split. To learn how these options work, see Set the OpenAPI basePath Property in API Gateway documentation.

    • Update definition with extensions – This option affects the way the integration handles the changes in your API definition, such as new parameters or renamed paths.

      • Disabled – The request and response mappings in API Gateway will be updated automatically based on the current paths and parameters in your API definition. API Gateway extensions (x-amazon-gateway-*) will not be added to your API definition, but if they exist, SwaggerHub will create mappings based on these extensions.

      • Enabled – SwaggerHub will add the x-amazon-gateway-* extensions to your API definition that contains the request and response mappings for API Gateway, and the integration will create mappings based on these extensions. Note that the extensions are never updated once they are created. For example, added or changed parameters will not be reflected here. To update the extensions (and the corresponding mappings in API Gateway), you will have to delete the extensions and save your API definition so that SwaggerHub can recreate them.

        If this option is enabled, SwaggerHub may also make changes to the API definition to make it compliant with the Amazon API Gateway limitations. This includes disabling the example and readOnly properties, removing xml keys, and simplifying model definition names. Disabled features will be wrapped into the x-disabled-for-amazon-gateway extension property.

    • Deployment Mode – Must be on save. Here, “deployment” refers to the action of pushing the definition to API Gateway (it doesn’t refer to the AWS “Deploy API” action).

    • Execution role for creating non-existing Lambda functions –The default execution role that will be assigned to new Lambda functions created by SwaggerHub. Specify the role ARN, it looks like arn:aws:iam::{account-id}:role/{role-name}. The existing functions and their roles will not be changed, SwaggerHub will create only the missing functions.

      If all Lambda functions already exist and you are not going to recreate them, leave this field blank.

    • Runtime – The programming language for the generated Lambda functions. The supported runtimes are:

      • Node.js 18.x

      • Node.js 16.x

      • Node.js 14.x

      • Node.js 12.x

      • Python 3.9

      • Python 3.8

      • Python 3.7

      • Python 3.6

    • AWS Access Key and AWS Secret Keys – The keys required to authorize SwaggerHub to connect to Amazon API Gateway. See above.

    • Enable – Enables or disables the integration.

  8. Click Create and Execute. SwaggerHub will publish your API definition to API Gateway and will create Lambda functions for all operations. This may take a few seconds depending on how large your API is.

  9. Click Done to close the integration settings.

Step 4. Push the API to Amazon API Gateway

SwaggerHub pushes your API to Amazon API Gateway (creating the necessary Lambda functions) every time you save the API in SwaggerHub. If there was a problem with pushing the API to API Gateway, you will see an error at the top of the SwaggerHub Editor.

To see your API in API Gateway:

  1. Open the Amazon API Gateway console at

  2. In the top right corner, select the region you have pushed to.

  3. Click your API in the APIs list. The API name is the same as info.title in your API definition.

    API in Amazon API Gateway

    Click the image to enlarge it.

Step 5. Modify Lambda functions

Each API operation is backed by a Lambda function in AWS. SwaggerHub generates function stubs, which you can later edit in Amazon to implement the business logic. Note that SwaggerHub does not overwrite any functions once they are created – it uses the function names to uniquely identify them.

To view the generated Lambda functions:

  1. In API Gateway, select your API, then select a method in the list, for example, /user > /{userName} > GET. You will see the Gateway configuration for that method.

  2. Note that the Integration Request section indicates that the back end type is LAMBDA. A link to the function is displayed on the right (in this case – getUserByName).

    Method execution parameters in API Gateway

    Click the image to enlarge it.

  3. Click the function name. The function code will open in a new tab.

    Lambda function code in AWS

    Click the image to enlarge it.

The default Node.js function code looks like this:

exports.handler = function(event, context, callback) {
  // string: (required)  The name that needs to be fetched. Use user1 for testing. 
  var username = event.username;
  callback(null, {
    message: 'created by SwaggerHub'

And, the default Python function code looks like this:

def lambda_handler(event, context):
  # string: (required)  The name that needs to be fetched. Use user1 for testing.
  username = event.get('username')

  return 'created by SwaggerHub'

The event object provides access to the operation parameters passed in the request. In our example, the operation GET /user/{username} has just one parameter, username, which can be accessed as event.username. The autogenerated variables at the top store individual parameter values.

The returned value is specified by using the callback in Node.js or the return statement in Python.

To learn more about writing Lambda functions, see AWS Lambda documentation:

go.gifAWS Lambda Function Handler in Node.js

go.gifAWS Lambda Function Handler in Python

Let’s modify the function to pass the received user name back to the caller. If you use Node.js, replace

  callback(null, {
    message: 'created by SwaggerHub'


  callback(null, {
    message: 'created by SwaggerHub',
    username: event.username

If you use Python, replace

    return 'created by SwaggerHub'


  response = {
      "username" : username

  return response

Then click Save to save the new code.

To test the function:

  1. Go back to API Gateway and select the /user > /{userName} > GET method.

  2. Click Test.

    Testing a request
  3. Enter any user name and click Test.

  4. Note that the same user name is included in the response.

    A response from the Lambda function

    Click the image to enlarge it.

Recreate Lambda functions

SwaggerHub does not overwrite any Lambda functions once they are created. For example, new or changed parameters in your API definition will not be reflected automatically in the Lambda functions.

To recreate a specific function with the latest definition, do the following:

  1. Delete the Lambda function in AWS (the actual function, not just its code).

  2. Delete the x-amazon-gateway-* extension for the corresponding operation in your API definition.

  3. Save your API definition.

SwaggerHub will recreate the missing function.

Disable Amazon API Gateway Lambda Sync

If you no longer want to sync your API definition and Lambda functions with Amazon API Gateway, you can do any of the following:

  • Disable the integration by unchecking the Enable check box in the integration parameters.

  • Set the Deployment Mode to never (this is the same as disabling the integration).

  • Delete the integration.

Your API and Lambda functions will remain in Amazon API Gateway, but SwaggerHub will not update them anymore.


The following limitations apply when importing OpenAPI definitions to Amazon API Gateway. Please note that these are the specifics of the Amazon API Gateway platform, not of SwaggerHub.

  • Amazon API Gateway known issues.

  • Query and header parameter names can contain only the following characters: A-Z a-z 0-9 - . _ $.

  • Models with circular references are not supported.

  • default responses are imported as 200 responses, unless the operation has a 200 response definition (in this case, the default response is ignored).

  • Additional considerations for OpenAPI 2.0:

    • Form parameters (in: formData) are not supported and are ignored.

  • Additional considerations for OpenAPI 3.0:

    • Cookie parameters (in: cookie) are not supported and are ignored.

    • Response code ranges (4XX) are not supported. Use specific response codes instead.

    • TRACE operation definitions are not supported. Use the x-amazon-apigateway-any-method extension to handle TRACE operations.

SwaggerHub will try to disable some unsupported keywords in your API definition by wrapping them into the x-disabled-for-amazon-gateway extension property. However, we recommend that you review your API definition manually and modify it to make it compatible with AWS.

See Also

Publication date: