ASP.NET Core in .NET 9 brings a streamlined and powerful way to create OpenAPI documents for your API endpoints. This new built-in support simplifies your development workflow and enhances the integration of OpenAPI definitions into your applications. With the growing ecosystem of tools like Swagger UI, Redoc, and the Kiota client library generator, this feature opens new possibilities for building, testing, and documenting APIs more effectively.

Why OpenAPI?

OpenAPI provides a standard way to define and document HTTP APIs. It describes your API’s endpoints, request and response formats, authentication schemes, and more. This standardization:

  • Improves developer collaboration.
  • Makes APIs easier to consume.
  • Enables seamless integration with tools and services.

Additionally, many large language models (LLMs) have been trained on OpenAPI documents, enabling automated code generation, testing, and more. By adopting OpenAPI, you unlock the potential to accelerate your development process.

Key Features in .NET 9

With .NET 9, OpenAPI document generation becomes more integrated and user-friendly. Highlights include:

  • Runtime and build-time OpenAPI document generation.
  • Attributes and extension methods for metadata annotation.
  • Transformer APIs for custom document modifications.
  • Multiple OpenAPI document generation from a single app.
  • JSON schema support via System.Text.Json.
  • Compatibility with native AOT in Minimal APIs.

Getting Started with OpenAPI in .NET 9

  1. Update to .NET 9Ensure your project targets .NET 9. You can download it from the official .NET website. For existing projects, follow the migration guide available in the ASP.NET Core docs.

Enable OpenAPI SupportIf starting a new project, OpenAPI is built into the .NET 9 WebAPI template. For existing projects:

dotnet add package Microsoft.AspNetCore.OpenApi

In Program.cs, add OpenAPI services:

builder.Services.AddOpenApi();
app.MapOpenApi();

Add Metadata for ClarityEnhance your OpenAPI documents by adding descriptions, summaries, tags, and parameter details using attributes or extension methods:

app.MapGet("/hello", () => "Hello, World!")
   .WithSummary("Get a greeting")
   .WithDescription("This endpoint returns a friendly greeting.")
   .WithTag("Greetings");

Customize Your OpenAPI DocumentsUse transformers to modify your documents:

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Contact = new OpenApiContact
        {
            Name = "Support",
            Email = "support@yourcompany.com"
        };
        return Task.CompletedTask;
    });
});

Generate OpenAPI Documents at Build Time

For integration into CI/CD workflows, generate OpenAPI documents during the build process. Install the Microsoft.Extensions.ApiDescription.Server package and configure your project:

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

This allows for tasks like linting, client code generation, and automated testing to be seamlessly integrated into your development pipeline.

Conclusion

The built-in OpenAPI support in .NET 9 revolutionizes how developers approach API documentation and integration. Whether you're building Minimal APIs or controller-based applications, this feature ensures your APIs are well-documented, easy to consume, and in sync with your code. With Assemblysoft's expertise in .NET and API development, we can help you harness these new capabilities to create robust, future-proof applications.

Contact us today to learn how Assemblysoft can elevate your API development!