Skip to main content

Configuration Options

LambdaOpenAPI uses MSBuild properties and targets to control OpenAPI specification generation. This guide covers all configuration options available in your project file (.csproj).

MSBuild Properties​

Core Properties​

PropertyDescriptionDefault
OpenApiOutputPathOutput path for the generated spec$(ProjectDir)openapi.json
EmitCompilerGeneratedFilesOutput source generator files for debuggingfalse
CompilerGeneratedFilesOutputPathDirectory for generated source files$(BaseIntermediateOutputPath)\GeneratedFiles

Basic Configuration​

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    
    <!-- Enable generated file output for debugging -->
    <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
    <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GeneratedFiles</CompilerGeneratedFilesOutputPath>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Oproto.Lambda.OpenApi" Version="1.0.0" />
  </ItemGroup>
</Project>

Output Path Configuration​

By default, the OpenAPI specification is generated to openapi.json in your project directory.

Custom Output Location​

Override the GenerateOpenApi target to change the output path:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Oproto.Lambda.OpenApi" Version="1.0.0" />
  </ItemGroup>

  <!-- Custom output path -->
  <Target Name="CustomOpenApiOutput" AfterTargets="GenerateOpenApi">
    <Copy SourceFiles="$(ProjectDir)openapi.json" 
          DestinationFiles="$(ProjectDir)docs\api\openapi.json" 
          SkipUnchangedFiles="true" />
  </Target>
</Project>

Multiple Output Locations​

Copy the specification to multiple locations for deployment and documentation:

<Target Name="CopyOpenApiToMultipleLocations" AfterTargets="GenerateOpenApi">
  <ItemGroup>
    <OpenApiDestinations Include="$(ProjectDir)docs\openapi.json" />
    <OpenApiDestinations Include="$(SolutionDir)api-docs\$(ProjectName).json" />
  </ItemGroup>
  
  <Copy SourceFiles="$(ProjectDir)openapi.json" 
        DestinationFiles="@(OpenApiDestinations)" 
        SkipUnchangedFiles="true" />
</Target>

AOT (Ahead-of-Time) Compilation Support​

LambdaOpenAPI fully supports Native AOT builds without any special configuration. The OpenAPI specification is extracted during the Build phase (before AOT compilation), so it works seamlessly with AOT projects.

How It Works​

The build task runs AfterTargets="Build", which executes before AOT publishing:

  1. Build → IL assembly created with attributes → OpenAPI extraction runs → openapi.json generated
  2. Publish → AOT compiles IL to native binary

The extraction uses MetadataLoadContext to read assembly metadata without loading dependencies, making it compatible with any project configuration.

AOT Build Configuration Example​

No special configuration is required for AOT projects:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <PublishAot>true</PublishAot>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Oproto.Lambda.OpenApi" Version="1.0.0" />
  </ItemGroup>
</Project>

Optional: Emitting Generated Files for Debugging​

If you want to inspect the generated source code for debugging purposes, you can optionally enable compiler-generated file output:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

This is not required for OpenAPI generation to work — it's purely for debugging the source generator output.

Disabling Generation​

Disable for Specific Configurations​

Disable generation only for Release builds:

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <OpenApiGenerationEnabled>false</OpenApiGenerationEnabled>
</PropertyGroup>

<Target Name="GenerateOpenApi" AfterTargets="Build" 
        Condition="'$(OpenApiGenerationEnabled)' != 'false'">
  <!-- Generation logic -->
</Target>

Disable Completely​

To completely disable OpenAPI generation:

<Target Name="GenerateOpenApi" />

Or conditionally:

<PropertyGroup>
  <SkipOpenApiGeneration>true</SkipOpenApiGeneration>
</PropertyGroup>

Disable via Command Line​

dotnet build -p:SkipOpenApiGeneration=true

Disable in CI Environments​

<Target Name="GenerateOpenApi" AfterTargets="Build" 
        Condition="'$(CI)' != 'true'">
  <!-- Only generate locally, not in CI -->
</Target>

Debugging Generated Files​

When troubleshooting generation issues, enable compiler-generated file output:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
  <CompilerGeneratedFilesOutputPath>$(BaseIntermediateOutputPath)\GeneratedFiles</CompilerGeneratedFilesOutputPath>
</PropertyGroup>

Generated files appear in:

obj/GeneratedFiles/Oproto.Lambda.OpenApi.SourceGenerator/

Troubleshooting​

OpenAPI File Not Generated​

Symptoms: Build succeeds but no openapi.json file is created.

Solutions:

  1. Missing [GenerateOpenApiSpec] attribute

    • Ensure at least one class has the [GenerateOpenApiSpec] attribute

  2. No Lambda functions detected

    • Verify methods have both [LambdaFunction] and [HttpApi] or [RestApi] attributes
    • Check that Amazon.Lambda.Annotations package is referenced

  3. Build task not running

    • Verify the package reference is correct
    • Check build output for warnings or errors

Generated Spec is Empty​

Symptoms: The openapi.json file exists but contains no endpoints.

Solutions:

  1. Missing HTTP method attributes 
    // ✅ Correct
    [LambdaFunction]
    [HttpApi(LambdaHttpMethod.Get, "/products")]
    public Task<Product[]> GetProducts() { }

    // ❌ Incorrect — missing HttpApi
    [LambdaFunction]
    public Task<Product[]> GetProducts() { }

Schema Not Generated for Models​

Symptoms: Request/response models appear as empty objects.

Solutions:

  1. Properties are not public — Ensure model properties have public getters
  2. Properties marked with [OpenApiIgnore] — Check for accidental exclusions
  3. Missing XML documentation — While not required, XML docs improve descriptions

Build Errors​

Symptoms: Build fails with source generator errors.

Solutions:

  1. Version conflicts — Ensure compatible package versions

    dotnet clean && dotnet build

  2. Missing dependencies

    <PackageReference Include="Amazon.Lambda.Annotations" Version="1.6.1" />
    <PackageReference Include="Oproto.Lambda.OpenApi" Version="1.0.0" />

  3. IDE caching issues — Restart your IDE, delete obj and bin folders

Viewing Generator Diagnostics​

Enable verbose MSBuild output:

dotnet build -v detailed

Look for messages starting with "OpenAPI Generation" in the build output.

Getting Help​

If you continue to experience issues:

  1. Check GitHub Issues for known problems
  2. Enable verbose logging and include output when reporting issues
  3. Include your project configuration and attribute usage in bug reports

See Also​