aspnetcore/fundamentals/openapi/aspnetcore-openapi.md
:::moniker range=">= aspnetcore-10.0"
The Microsoft.AspNetCore.OpenApi package provides built-in support for OpenAPI document generation in ASP.NET Core. The package provides the following features:
The default OpenAPI version for generated documents is 3.1. The version can be changed by explicitly setting the xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions.OpenApiVersion%2A property of the xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions in the configureOptions delegate parameter of xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A:
builder.Services.AddOpenApi(options =>
{
// Specify the OpenAPI version to use
options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
});
When generating the OpenAPI document at build time, the OpenAPI version can be selected by setting the --openapi-version in the OpenApiGenerateDocumentsOptions MSBuild item.
<!-- Configure build-time OpenAPI generation to produce an OpenAPI 3.1 document -->
<OpenApiGenerateDocumentsOptions>--openapi-version OpenApi3_1</OpenApiGenerateDocumentsOptions>
Install the Microsoft.AspNetCore.OpenApi package:
Run the following command from the Package Manager Console:
Install-Package Microsoft.AspNetCore.OpenApi
Run the following command in a command shell opened to the directory that contains the app's project file:
dotnet add package Microsoft.AspNetCore.OpenApi
The following code:
Launch the app and navigate to https://localhost:{port}/openapi/v1.json to view the generated OpenAPI document, where the {port} placeholder is the port.
The following sections demonstrate how to customize OpenAPI document generation.
The OpenAPI document can be generated in either JSON or YAML format. By default, the OpenAPI document is generated in JSON format. To generate the OpenAPI document in YAML format, specify the endpoint in the xref:Microsoft.AspNetCore.Builder.OpenApiEndpointRouteBuilderExtensions.MapOpenApi%2A call with a ".yaml" or ".yml" suffix, as shown in the following example, where the {documentName} placeholder is the document name:
app.MapOpenApi("/openapi/{documentName}.yaml");
Generating OpenAPI documents in YAML format at build time isn't supported but planned for a future preview.
Each OpenAPI document in an app has a unique name. The default document name that is registered is v1:
builder.Services.AddOpenApi(); // Document name is v1
The document name can be modified by passing the name as a parameter to the xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A call:
builder.Services.AddOpenApi("internal"); // Document name is internal
The document name surfaces in several places in the OpenAPI implementation.
When fetching the generated OpenAPI document, the document name is provided as the documentName parameter argument in the request. The following requests resolve the v1 and internal documents.
GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json
By default, OpenAPI document generation creates a document that is compliant with the OpenAPI specification. The following code demonstrates how to modify the default version of the OpenAPI document:
builder.Services.AddOpenApi(options =>
{
options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});
By default, the OpenAPI endpoint registered via a call to xref:Microsoft.AspNetCore.Builder.OpenApiEndpointRouteBuilderExtensions.MapOpenApi%2A exposes the document at the /openapi/{documentName}.json endpoint. The following code demonstrates how to customize the route at which the OpenAPI document is registered:
app.MapOpenApi("/openapi/{documentName}/openapi.json");
It's possible, but not recommended, to remove the documentName route parameter from the endpoint route. When the documentName route parameter is removed from the endpoint route, the framework attempts to resolve the document name from the query parameter. Not providing the documentName in either the route or query can result in unexpected behavior.
Because the OpenAPI document is served via a route handler endpoint, any customization that is available to standard minimal endpoints is available to the OpenAPI endpoint.
The OpenAPI endpoint doesn't enable authorization checks by default. However, authorization checks can be applied to the OpenAPI document. In the following code, access to the OpenAPI document is limited to users with the tester role:
The OpenAPI document is regenerated every time a request to the OpenAPI endpoint is sent. Regeneration enables transformers to incorporate dynamic app state into their operation. For example, regenerating a request with details of the HTTP context. When applicable, the OpenAPI document can be cached to avoid executing the document generation pipeline on each HTTP request.
In some scenarios, it's helpful to generate multiple OpenAPI documents with different content from a single ASP.NET Core API app. These scenarios include generating OpenAPI documentation for different:
To generate multiple OpenAPI documents, call the xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A extension method once for each document, specifying a different document name in the first parameter each time.
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
Each invocation of xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A can specify its own set of options, so you can choose to use the same or different customizations for each OpenAPI document.
The framework uses the xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions.ShouldInclude delegate method of xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions to determine which endpoints to include in each document.
For each document, the xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions.ShouldInclude delegate method is called for each endpoint in the app, passing the xref:Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription object for the endpoint. The method returns a boolean value indicating whether the endpoint should be included in the document. The xref:Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription object:
The default implementation of this delegate uses the xref:Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription.GroupName field of xref:Microsoft.AspNetCore.Mvc.ApiExplorer.ApiDescription. The delegate is set on an endpoint using either the xref:Microsoft.AspNetCore.Builder.RoutingEndpointConventionBuilderExtensions.WithGroupName%2A extension method or the xref:Microsoft.AspNetCore.Routing.EndpointGroupNameAttribute attribute. WithGroupName or the EndpointGroupName attribute determines which endpoints to include in the document. Any endpoint that hasn't been assigned a group name is included all OpenAPI documents.
// Include endpoints without a group name or with a group name
// that matches the document name
ShouldInclude = (description) => description.GroupName == null ||
description.GroupName == DocumentName;
You can customize the xref:Microsoft.AspNetCore.OpenApi.OpenApiOptions.ShouldInclude delegate method to include or exclude endpoints based on any criteria.
[!NOTE] Starting with .NET 9, ASP.NET Core includes built-in OpenAPI support. The
Microsoft.AspNetCore.OpenApipackage provides OpenAPI document generation at runtime, and adding theMicrosoft.Extensions.ApiDescription.Serverpackage enables build-time document generation.ASP.NET Core generates OpenAPI documents only. Interactive UIs such as Swagger UI or Scalar are not included by default and must be added separately. For guidance on using these UI options, see xref:fundamentals/openapi/using-openapi-documents.
In typical web apps, OpenAPI documents are generated at runtime and served via an HTTP request to the app server.
In some scenarios, it's helpful to generate the OpenAPI document during the app's build step. These scenarios include generating OpenAPI documentation that is:
To add support for generating OpenAPI documents at build time, install the Microsoft.Extensions.ApiDescription.Server package:
Run the following command from the Package Manager Console:
Install-Package Microsoft.Extensions.ApiDescription.Server
Run the following command in a command shell opened to the directory that contains the app's project file:
dotnet add package Microsoft.Extensions.ApiDescription.Server
Upon installation, this package:
If multiple documents are registered and the document name is not v1, the project name is post-fixed with the document name. Example: {ProjectName}_{DocumentName}.json. The {ProjectName} placeholder is the project name, and the {DocumentName} placeholder is the document name.
dotnet build
type obj\{ProjectName}.json
dotnet build
cat obj/{ProjectName}.json
When Microsoft.Extensions.ApiDescription.Server runs the :::no-loc text="GetDocument"::: step during dotnet build, progress messages aren't visible with the .NET Terminal Logger at default verbosity in .NET 8 or later. To surface these messages while building, use either of the following options with the dotnet build command.
Set the Terminal Logger's verbosity with the -tlp option set to v=d (verbosity = detailed):
dotnet build -tlp:v=d
Disable the Terminal Logger and use legacy-style logs with the --tl option set to off:
dotnet build --tl:off
By default, the generated OpenAPI document is emitted to the app's output directory. To modify the location of the emitted file, set the target path in the OpenApiDocumentsDirectory property:
<PropertyGroup>
<OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
</PropertyGroup>
The value of OpenApiDocumentsDirectory is resolved relative to the project file. Using the . value, as seen in the preceding example, emits the OpenAPI document in the same directory as the project file.
By default, the generated OpenAPI document has the same name as the app's project file. To modify the name of the emitted file, set the --file-name argument in the OpenApiGenerateDocumentsOptions property:
<PropertyGroup>
<OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>
Some apps may be configured to emit multiple OpenAPI documents. Multiple OpenAPI documents may be generated for different versions of an API or to distinguish between public and internal APIs. By default, the build-time document generator emits files for all documents that are configured in an app. To only emit for a single document name, set the --document-name argument in the OpenApiGenerateDocumentsOptions property:
<PropertyGroup>
<OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>
Build-time OpenAPI document generation functions by launching the apps entrypoint with a mock server implementation. A mock server is required to produce accurate OpenAPI documents because all information in the OpenAPI document can't be statically analyzed. Because the apps entrypoint is invoked, any logic in the apps startup is invoked. This includes code that injects services into the DI container or reads from configuration. In some scenarios, it's necessary to restrict the code paths when the app's entry point is invoked from build-time document generation. These scenarios include:
In order to restrict invoking these code paths by the build-time generation pipeline, they can be conditioned behind a check of the entry assembly:
:::code language="csharp" source="~/fundamentals/openapi/samples/9.x/AspireApp1/AspireApp1.Web/Program.cs" highlight="5-8":::
AddServiceDefaults adds common Aspire services such as service discovery, resilience, health checks, and OpenTelemetry.
OpenAPI in ASP.NET Core supports trimming and native AOT. The following steps create and publish an OpenAPI app with trimming and native AOT.
Create a new ASP.NET Core Web API (Native AOT) project:
dotnet new webapiaot
Publish the app:
dotnet publish
:::moniker-end