Automating OpenAPI and SDK Generation for .NET 8 Minimal APIs with Source Generators

Why automate OpenAPI and SDK creation for .NET 8?

Imagine a team that releases a new Minimal API endpoint every sprint, yet the consumer SDKs lag behind by weeks. In 2023, 68% of enterprises reported that manual OpenAPI maintenance caused integration delays (TechTarget). Automating both the OpenAPI document and the client SDK eliminates that bottleneck, keeping contracts in sync and reducing human error.

Understanding .NET 8 Minimal APIs

.NET 8 refines the Minimal API model introduced in .NET 6, allowing developers to define HTTP verbs with a single lambda. The result is a lightweight project that compiles to a small binary, ideal for micro‑services. For example, a simple weather endpoint can be expressed in under 15 lines of C#.

var builder = WebApplication.CreateBuilder(args);var app = builder.Build();app.MapGet("/weather", (ILogger logger) => {logger.LogInformation("Weather requested");return new[]{new{Date=DateTime.UtcNow,TempC=22}};});app.Run();

Because the routing table is built at compile time, the runtime overhead is negligible, but the lack of a built‑in OpenAPI generator for Minimal APIs means developers often resort to external tools.

Source Generators for OpenAPI generation

Source generators run during compilation and can inspect the syntax tree. Microsoft introduced the Microsoft.AspNetCore.OpenApi package for .NET 8, which ships a generator that emits a openapi.json file alongside the assembly. To enable it, add the package and set GenerateOpenApi to true in the project file.

net8.0true

When the build finishes, a wwwroot/openapi.json file appears, reflecting every MapGet, MapPost, and parameter annotation. The generator respects [FromQuery], [FromBody], and custom validation attributes, producing a spec that tools like Swagger UI can consume without extra configuration.

Integrating Azure API Center

Azure API Center acts as a catalog and governance layer for APIs across an organization. By publishing the generated OpenAPI file to Azure API Center, you gain versioning, policy enforcement, and analytics in a single pane. The publishing step can be scripted with Azure CLI:

az apicenter api create \
  --resource-group MyRG \
  --service-name MyApiCenter \
  --api-id weather-v1 \
  --spec-path ./wwwroot/openapi.json \
  --display-name "Weather Service" \
  --description "Minimal API for weather forecasts"

This command registers the spec, creates a stable endpoint like https://myapicenter.azure.com/apis/weather-v1, and automatically enables security policies defined at the portal level.

Generating client SDKs automatically

Once the OpenAPI document lives in Azure API Center, the platform can produce client SDKs for multiple languages on demand. For .NET consumers, the dotnet-openapi tool can generate a strongly‑typed SDK directly from the Azure URL:

dotnet tool install -g dotnet-openapi
 dotnet openapi add \
   --url https://myapicenter.azure.com/apis/weather-v1/openapi.json \
   --output GeneratedSdk \
   --namespace Weather.Client

The resulting Weather.Client library contains POCO models, a WeatherClient class with async methods, and built‑in retry policies. Adding the SDK to a consuming project is as simple as a NuGet reference to the local folder.

Practical tips and common pitfalls

1. **Keep the generator on the same SDK version** – mismatched Microsoft.AspNetCore.OpenApi versions can produce invalid JSON. Use the global.json file to lock the .NET SDK to 8.0.200 or later.
2. **Validate the spec before publishing** – run dotnet openapi validate against the generated file to catch schema errors early.
3. **Version the API in the URL** – Azure API Center treats each version as a distinct entity; include /v1 or /v2 in the spec's info.version field.
4. **Avoid circular dependencies** – the generated SDK should not reference the server project. Keep them in separate solution folders.

Performance testing shows that a Minimal API with a source‑generated OpenAPI spec adds less than 5 ms of startup overhead on a typical Azure App Service instance (Azure Benchmarks, Q2 2024). This trade‑off is negligible compared to the time saved on manual documentation.

Conclusion

Automating OpenAPI specification and client SDK generation transforms a .NET 8 Minimal API from a prototype into a production‑grade service. Source generators keep the contract accurate at compile time, Azure API Center provides governance and distribution, and the dotnet-openapi CLI delivers ready‑to‑use .NET clients. By embedding these steps into CI pipelines, teams can release new endpoints daily without breaking downstream applications.

Sources

Microsoft Docs – .NET 8 Minimal APIs
Azure Documentation – API Center Overview
TechTarget – API Management Survey 2023

Author: Mahmut Sarıkaya — sarikayadev.com