AWS Lambda transport for Swift OpenAPI

This library provides an AWS Lambda transport for Swift OpenAPI generator

This library allows you to expose server-side Swift OpenAPI implementations as AWS Lambda functions with minimal code changes.

The library provides:

• A default AWS Lambda Swift function that consumes your OpenAPI service implementation
• Built-in support for Amazon API Gateway HTTP API events
• Re-exported dependencies to minimize Package.swift complexity

We strongly recommend to never deploy openly available API. The QuoteAPI example project shows you how to add a Lambda Authorizer function to the API Gateway.

Prerequisites

• AWS Account
• AWS CLI - configured with your AWS credentials
• AWS SAM CLI - for serverless deployment
• Docker Desktop - for cross compilation to Linux, when using macOS or Windows.

Quick Start

If you already have an OpenAPI definition, you already generated the server stubs, and wrote an implementation, here are the additional steps to expose your OpenAPI service implementation as a AWS Lambda function and an Amazon API Gateway HTTP API (aka APIGatewayV2).

To expose your OpenAPI implementation as an AWS Lambda function:

1. Add dependencies to Package.swift

dependencies: [
    .package(url: "https://github.com/apple/swift-openapi-generator.git", from: "1.4.0"),
    .package(url: "https://github.com/apple/swift-openapi-runtime.git", from: "1.8.2"),
    
    // add these three dependencies
    .package(url: "https://github.com/swift-server/swift-aws-lambda-runtime.git", from: "2.0.0-beta.3"),
    .package(url: "https://github.com/swift-server/swift-aws-lambda-events.git", from: "1.2.0"),
    .package(url: "https://github.com/swift-server/swift-openapi-lambda.git", from: "2.0.0"),
],
targets: [
  .executableTarget(
    name: "YourOpenAPIService",
    dependencies: [
      .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),

      // add these three products
      .product(name: "AWSLambdaRuntime", package: "swift-aws-lambda-runtime"),
      .product(name: "AWSLambdaEvents", package: "swift-aws-lambda-events"),
      .product(name: "OpenAPILambda", package: "swift-openapi-lambda"),
    ]
  )
]

2. Update your service implementation

Add a protocol and a constructor to your existing OpenAPI service implementation

There are only five changes to make to your existing implementation:

import OpenAPIRuntime
import OpenAPILambda // <-- 1. import this library 

@main // <-- 2. flag this struct as the executable target entrypoint
struct QuoteServiceImpl: APIProtocol, OpenAPILambdaHttpApi { // <-- 3. add the OpenAPILambdaHttpApi protocol 

  // The registration of your OpenAPI handlers
  func register(transport: OpenAPILambdaTransport) throws { // <-- 4. add this method (calls registerHandlers)
    try self.registerHandlers(on: transport)
  }

  // the entry point for your Lambda function
  static func main() async throws { // <-- 5. add this entry point to start the lambdaRuntime
    let openAPIService = QuoteServiceImpl()  
    try await openAPIService.run()
  }

  // Your existing OpenAPI implementation
  func getQuote(_ input: Operations.getQuote.Input) async throws -> Operations.getQuote.Output {
    let symbol = input.path.symbol
    let price = Components.Schemas.quote(
        symbol: symbol,
        price: Double.random(in: 100..<150).rounded(),
        change: Double.random(in: -5..<5).rounded(),
        changePercent: Double.random(in: -0.05..<0.05),
        volume: Double.random(in: 10000..<100000).rounded(),
        timestamp: Date()
    )
    return .ok(.init(body: .json(price)))
  }
}

3. Deploy with SAM

sam build && sam deploy --guided

Complete Example

See the Examples/quoteapi directory for a complete working example that includes:

• Stock quote API with OpenAPI 3.1 specification
• Lambda authorizer for protected endpoints
• Use make for common commands
• SAM deployment configuration
• Local testing setup

Testing

Local Development

# Run locally with built-in development server
swift run QuoteService

# Test from another terminal
curl -H 'Authorization: Bearer 123' -X POST \
  --data @events/GetQuote.json \
  http://127.0.0.1:7000/invoke

Production Testing

# Test deployed API (replace with your endpoint)
curl -H 'Authorization: Bearer 123' \
  https://your-api-id.execute-api.region.amazonaws.com/stocks/AAPL

Deployment Costs

New AWS accounts get 1 million Lambda invocations and 1 million API Gateway requests free per month. After the free tier, costs are approximately $1.00 per million API calls.

Cleanup

sam delete

Lambda Authorizers

The library supports Lambda authorizers for API protection. See Examples/quoteapi/Sources/LambdaAuthorizer for a complete implementation that validates a Bearer token.

let simpleAuthorizerHandler: (APIGatewayLambdaAuthorizerRequest, LambdaContext) async throws -> APIGatewayLambdaAuthorizerSimpleResponse = {
    guard let authToken = $0.headers["authorization"],
          authToken == "Bearer 123" else {
        return .init(isAuthorized: false, context: [:])
    }
    return .init(isAuthorized: true, context: ["user": "authenticated"])
}

Advanced Usage

Custom Event Types

To support other Lambda event types beyond API Gateway, implement the OpenAPILambda protocol:

@main
struct CustomServiceLambda: OpenAPILambda {
  typealias Event = YourCustomEvent
  typealias Output = YourCustomResponse
  
  func register(transport: OpenAPILambdaTransport) throws {
    let handler = YourServiceImpl()
    try handler.registerHandlers(on: transport)
  }
  
  func request(context: LambdaContext, from event: Event) throws -> OpenAPILambdaRequest {
    // Transform your event to HTTPRequest
  }
  
  func output(from response: OpenAPILambdaResponse) -> Output {
    // Transform HTTPResponse to your output type
  }
}

Service Lifecycle Integration

import ServiceLifecycle

// In your OpenAPI service, explicitly create and manage the LambdaRuntime
static func main() async throws {
  let lambdaRuntime = try LambdaRuntime(body: Self.handler())
  let serviceGroup = ServiceGroup(
    services: [lambdaRuntime],
    gracefulShutdownSignals: [.sigterm],
    cancellationSignals: [.sigint],
    logger: Logger(label: "ServiceGroup")
  )
  try await serviceGroup.run()
}

Dependency Injection

For advanced use cases requiring dependency injection:

@main
struct QuoteServiceImpl: APIProtocol, OpenAPILambdaHttpApi {
    let customDependency: Int
    
    init(customDependency: Int = 0) {
        self.customDependency = customDependency
    }
    
    // the entry point can be in another file / struct as well.
    static func main() async throws {
        let service = QuoteServiceImpl(customDependency: 42)
        let lambda = try OpenAPILambdaHandler(service: service)
        let lambdaRuntime = LambdaRuntime(body: lambda.handler)
        try await lambdaRuntime.run()
    }
    
    func register(transport: OpenAPILambdaTransport) throws {
        try self.registerHandlers(on: transport)
    }
}

References

• Swift OpenAPI Generator - Complete documentation and tutorials
• Swift AWS Lambda Runtime - Swift runtime for AWS Lambda
• AWS SAM - Serverless Application Model documentation
• API Gateway Lambda Authorizers - Lambda authorization documentation