Skip to main content

Introduction

Why This Project Exists​

AWS Lambda offers multiple ways to build HTTP-based APIs with .NET. Developers can host ASP.NET Core inside Lambda using the PROXY+ integration, or they can use the more serverless-native approach of deploying individual Lambda functions with AWS Lambda Annotations.

Running ASP.NET Core provides automatic OpenAPI generation through Swashbuckle or Microsoft’s OpenAPI framework. This is useful during development but comes with trade-offs:

  • larger deployment packages
  • slower cold starts
  • no Native AOT support
  • a full web framework running inside a short-lived compute environment
  • inability to right-size resource configuration (memory, timeout, provisioned concurrency) per operation when multiple routes run inside a single ASP.NET Lambda function

Many teams—including ours—eventually transition to the single-function model for efficiency, clarity, and AOT compatibility.

In this model, Lambda Annotations significantly improves handler ergonomics, but the OpenAPI workflow from ASP.NET Core is lost:

  • attributes no longer translate to OpenAPI metadata
  • API Gateway documentation is defined separately in CDK/CloudFormation
  • API Gateway does not expose a reliable OpenAPI export
  • documentation can drift away from implementation

There was no simple, code-first way to generate an OpenAPI document directly from Lambda functions.

LambdaOpenAPI was created to solve exactly that problem. It reads your Lambda Annotations attributes during compilation and produces an OpenAPI 3.x document that matches your actual function definitions. No hosting pipeline, no reflection, and no dependency on API Gateway’s documentation model.

This restores the benefits of code-driven API documentation while preserving the lightweight, serverless-native execution model of AWS Lambda.