Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 25 additions & 14 deletions aspnetcore/fundamentals/openapi/using-openapi-documents.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Learn how to use OpenAPI documents in an ASP.NET Core app.
ms.author: safia
monikerRange: '>= aspnetcore-6.0'
ms.custom: mvc
ms.date: 12/04/2025
ms.date: 01/13/2026
uid: fundamentals/openapi/using-openapi-documents
---
# Use openAPI documents
Expand Down Expand Up @@ -65,8 +65,8 @@ Enable document generation at build time by setting the following properties in

```xml
<PropertyGroup>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
<OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
<OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>
```

Expand Down Expand Up @@ -102,34 +102,45 @@ The output shows any issues with the OpenAPI document. For example:

## Support for injecting `IOpenApiDocumentProvider`

You can inject <xref:Microsoft.AspNetCore.OpenApi.IOpenApiDocumentProvider> into your services through dependency injection to access OpenAPI documents programmatically, even outside HTTP request contexts.
Inject <xref:Microsoft.AspNetCore.OpenApi.IOpenApiDocumentProvider> into services to access OpenAPI documents programmatically, even outside HTTP request contexts. The following example customizes version 2 ("`v2`") of the document with title, version, and description information:

```csharp
public class CustomDocumentService
{
private readonly IOpenApiDocumentProvider _documentProvider;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi;

public CustomDocumentService(IOpenApiDocumentProvider documentProvider)
public class CustomDocumentService(
[FromKeyedServices("v2")] IOpenApiDocumentProvider documentProvider)
{
public async Task<OpenApiDocument> GetApiDocumentAsync(
CancellationToken cancellationToken = default)
{
_documentProvider = documentProvider;
}
var document =
await documentProvider.GetOpenApiDocumentAsync(cancellationToken);

public async Task<OpenApiDocument> GetApiDocumentAsync()
{
return await _documentProvider.GetOpenApiDocumentAsync("v1");
document.Info = new OpenApiInfo
{
Title = "Custom API Title",
Version = "v2",
Description = "This is a custom API description for version 2."
};

return document;
}
}
```

Register the service in your DI container:
Register the service in your DI container. Note that service key should match the document name passed to <xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A>:

```csharp
builder.AddOpenApi(); // Adds "v1" by default
builder.AddOpenApi("v2");
builder.Services.AddScoped<CustomDocumentService>();
```

This enables scenarios such as generating client SDKs, validating API contracts in background processes, or exporting documents to external systems.

Support for injecting `IOpenApiDocumentProvider` was introduced in ASP.NET Core in .NET 10. For more information, see [dotnet/aspnetcore #61463](https://github.com/dotnet/aspnetcore/pull/61463).

:::moniker-end

[!INCLUDE[](~/fundamentals/openapi/includes/using-openapi-documents-6-8.md)]
Expand Down