Microsoft.AspNetCore.OpenApi 11.0.0-preview.7.26381.103

About

Microsoft.AspNetCore.OpenApi is a NuGet package that provides built-in support for generating OpenAPI documents from minimal or controller-based APIs in ASP.NET Core.

Key Features

• Supports viewing generated OpenAPI documents at runtime via a parameterized endpoint (/openapi/{documentName}.json)
• Supports generating an OpenAPI document at build-time
• Supports customizing the generated document via document transformers

How to Use

To start using Microsoft.AspNetCore.OpenApi in your ASP.NET Core application, follow these steps:

Installation

dotnet add package Microsoft.AspNetCore.OpenApi

Configuration

In your Program.cs file, register the services provided by this package in the DI container and map the provided OpenAPI document endpoint in the application.

var builder = WebApplication.CreateBuilder();

// Registers the required services
builder.Services.AddOpenApi();

var app = builder.Build();

// Adds the /openapi/{documentName}.json endpoint to the application
app.MapOpenApi();

app.Run();

For more information on configuring and using Microsoft.AspNetCore.OpenApi, refer to the official documentation.

Build-time Document Generation

Microsoft.AspNetCore.OpenApi supports generating OpenAPI documents at build time via the Microsoft.Extensions.ApiDescription.Server package. When you run dotnet build, the document generation tool runs automatically.

Viewing Build-time Generation Output

By default, the .NET 8+ Terminal Logger suppresses the document generation tool output. To see the full generation logs, including messages like Generating document named 'v1', use one of the following approaches:

• Increase Terminal Logger verbosity: Pass -tlp:v=d (detailed) to your build command:

  dotnet build -tlp:v=d
  

• Disable the Terminal Logger: Pass --tl:off to fall back to the classic logger, which shows all tool output:

  dotnet build --tl:off
  

This is particularly useful when debugging OpenAPI document generation issues.

Main Types

The main types provided by this library are:

• OpenApiOptions: Options for configuring OpenAPI document generation.
• IDocumentTransformer: Transformer that modifies the OpenAPI document generated by the library.

Feedback & Contributing

Microsoft.AspNetCore.OpenApi is released as open-source under the MIT license. Bug reports and contributions are welcome at the GitHub repository.