If you build .NET applications on AWS Lambda, you've probably seen two common patterns:
- running ASP.NET Core inside Lambda using the PROXY+ model
- or deploying individual Lambda functions, each with a single handler
The ASP.NET option has familiar benefits: controllers, middleware, and automatic OpenAPI generation through Swashbuckle or Microsoft's OpenAPI libraries.
But as cold starts and deployment size became increasingly important - especially with .NET's Native AOT support - many teams (including ours) moved away from hosting ASP.NET inside Lambda. The single-function model is lighter, faster, and more serverless-native.
The problem?
You lose automatic OpenAPI documentation.
Lambda Annotations: Clean, Modern Lambda Functions (Without ASP.NET)
Lambda Annotations is a small but very useful library in the AWS .NET ecosystem. It doesn't try to mimic ASP.NET routing, and it doesn't run a web framework inside Lambda. Instead, it makes single-operation Lambdas far cleaner to write:
[LambdaFunction]
[HttpApi]
public OutputModel DoThing(InputModel input) { ... }
Attributes replace boilerplate.
Inputs and outputs are bound automatically.
The handler reads like normal C#.
It's simple, efficient, and ideal for Lambda's single-responsibility model - exactly the style most teams adopt when using CDK + API Gateway.
But again: no built-in OpenAPI support.
The Documentation Gap After Leaving ASP.NET
Once you're no longer hosting ASP.NET Core, several things become true:
- Microsoft's OpenAPI middleware no longer runs
- Lambda Annotations doesn't produce OpenAPI
- API Gateway documentation is defined in CDK/CloudFormation, not C#
- And API Gateway's documentation model isn't easily exportable
You end up with clean, modern Lambda code - but no way to generate a complete OpenAPI 3.x spec directly from it.
And for teams building client SDKs, internal integration points, or automated documentation, that's a real limitation.
LambdaOpenAPI: Going Directly From Code → Spec
Instead of trying to synchronize:
- CDK route definitions
- API Gateway documentation structures
- and annotation metadata
- with what the code actually does
…we took a different approach.
Why We Built LambdaOpenAPI
Instead of trying to sync:
- CDK routes
- API Gateway documentation settings
- handler code
- and annotation metadata
we decided to generate the OpenAPI spec directly from the Lambda code at build time.
No hosting.
No middleware.
No runtime reflection.
No spec drift.
Just:
Your annotations → Your OpenAPI 3.x file → Automatically.
This preserves the simplicity of native Lambda functions while restoring the documentation workflow developers loved in ASP.NET.
To illustrate what "code → spec" looks like in practice, here's a minimal example.
LambdaOpenAPI consumes the same attributes you're already using with Lambda Annotations - plus a few assembly-level attributes for OpenAPI metadata. With just a handful of annotations, the generator produces a complete, compliant OpenAPI 3.x document at build time, no ASP.NET hosting or runtime components required.
// Assembly-level metadata
[assembly: OpenApiInfo("Products API", "1.0")]
[assembly: OpenApiServer("https://api.example.com/v1")]
[assembly: OpenApiTagDefinition("Products")]
// A simple Lambda operation
[LambdaFunction]
[HttpApi(LambdaHttpMethod.Get, "/products")]
[OpenApiOperation(Summary = "List products")]
[OpenApiTag("Products")]
public IEnumerable<Product> GetProducts([FromQuery] int limit = 50)
{
return ProductRepository.List(limit);
}
Why Lambda Annotations Deserves More Attention
Lambda Annotations isn't a routing engine and it's not a mini-framework. It's simply a cleaner, modernized way to write single-purpose Lambda functions:
- smaller deployments
- fast cold starts
- clean handler methods
- attribute-based metadata
- AOT-friendly patterns
- pairs well with CDK and API Gateway
It solves real developer pain without adding complexity - and yet it barely appears in AWS's public documentation. Most developers only discover it by accident.
If you're building .NET APIs on Lambda and aren't running ASP.NET Core inside your functions, Annotations provides a much more pleasant development experience.
And with build-time OpenAPI generation layered on top, it finally fills the documentation gap that appears when you step away from full ASP.NET hosting.
Worth Trying
If your Lambda handlers still start with APIGatewayProxyRequest and a block of manual parsing, Lambda Annotations is a major quality-of-life improvement. And if you miss the automatic OpenAPI generation you had in ASP.NET, tools like LambdaOpenAPI restore that workflow-without giving up the speed and simplicity of native Lambda functions.
It's a quiet feature, that deserves more attention in the AWS .NET world.
