Skip to content

Commit 83deab0

Browse files
wadepickettwadepickett
authored
Merge pull request #36909 from dotnet/main
Merge to Live
2 parents 232805a + 42e3f50 commit 83deab0

3 files changed

Lines changed: 81 additions & 19 deletions

File tree

aspnetcore/fundamentals/openapi/includes/overview6-8.md renamed to aspnetcore/fundamentals/openapi/includes/overview-6-8.md

File renamed without changes.

‎aspnetcore/fundamentals/openapi/includes/overview-9.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
:::moniker range="aspnetcore-9.0"
2+
3+
ASP.NET Core supports the generation of OpenAPI documents in controller-based and Minimal API apps.
4+
The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) is a programming language-agnostic standard for documenting HTTP APIs. This standard is supported in ASP.NET Core apps through a combination of built-in APIs and open-source libraries. There are three key aspects to OpenAPI integration in an application:
5+
6+
* Generating information about the endpoints in the app.
7+
* Gathering the information into a format that matches the OpenAPI schema.
8+
* Exposing the generated OpenAPI document via a visual UI or a serialized file.
9+
10+
ASP.NET Core provides first-party support for generating information about endpoints in an app through the `Microsoft.AspNetCore.OpenApi` package.
11+
12+
13+
The following code is generated by the ASP.NET Core minimal web API template and uses OpenAPI:
14+
15+
[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_default&highlight=5,9-12)]
16+
17+
In the preceding highlighted code:
18+
19+
* `AddOpenApi` registers services required for OpenAPI document generation into the application's DI container.
20+
* `MapOpenApi` adds an endpoint into the application for viewing the OpenAPI document serialized into JSON. The OpenAPI endpoint is restricted to the `Development` environment to minimize the risk of exposing sensitive information and reduce the vulnerabilities in production.
21+
22+
<a name="openapinuget"></a>
23+
24+
## `Microsoft.AspNetCore.OpenApi` NuGet package
25+
26+
The [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/) package provides the following features:
27+
28+
* Support for generating OpenAPI documents at run time and accessing them via an endpoint on the application.
29+
* Support for "transformer" APIs that modify the generated document.
30+
31+
To use the `Microsoft.AspNetCore.OpenApi` package, add it as a PackageReference to a project file:
32+
33+
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=15)]
34+
35+
To learn more about the `Microsoft.AspNetCore.OpenApi` package, see <xref:fundamentals/openapi/aspnetcore-openapi>.
36+
37+
## `Microsoft.Extensions.ApiDescription.Server` NuGet package
38+
39+
The [`Microsoft.Extensions.ApiDescription.Server`](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server/) package provides support for generating OpenAPI documents at build time and serializing them.
40+
41+
To use `Microsoft.Extensions.ApiDescription.Server`, add it as a PackageReference to a project file.
42+
Document generation at build time is enabled by setting the `OpenApiGenerateDocuments` property.
43+
By default, the generated OpenAPI document is saved to the `obj` directory, but you can customize
44+
the output directory by setting the `OpenApiDocumentsDirectory` property.
45+
46+
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)]
47+
48+
<!-- Include makes it trivial to move this anywhere in the doc OR add to other docs-->
49+
[!INCLUDE[](~/fundamentals/openapi/includes/api_endpoint_operation.md)]
50+
51+
## ASP.NET Core OpenAPI source code on GitHub
52+
53+
* [AddOpenApi](https://github.com/dotnet/aspnetcore/blob/main/src/OpenApi/src/Extensions/OpenApiServiceCollectionExtensions.cs)
54+
* [OpenApiDocumentService](https://github.com/dotnet/aspnetcore/blob/main/src/OpenApi/src/Services/OpenApiDocumentService.cs)
55+
* [OpenApiOptions](https://github.com/dotnet/aspnetcore/blob/main/src/OpenApi/src/Services/OpenApiOptions.cs)
56+
57+
## Additional Resources
58+
59+
* <xref:fundamentals/minimal-apis/security>
60+
61+
:::moniker-end

‎aspnetcore/fundamentals/openapi/overview.md‎

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,32 @@
11
---
22
title: Overview of OpenAPI support in ASP.NET Core API apps
3+
ai-usage: ai-assisted
34
author: wadepickett
4-
description: Learn about OpenAPI features in ASP.NET Core.
5-
ms.author: wpickett
5+
description: Learn how to integrate OpenAPI in ASP.NET Core API apps. Discover features, tools, and packages for generating and customizing OpenAPI documents.
66
monikerRange: '>= aspnetcore-6.0'
7-
ms.date: 05/14/2025
7+
ms.author: wpickett
8+
ms.reviewer: wpickett
9+
ms.date: 03/20/2026
810
uid: fundamentals/openapi/overview
911
---
1012
# OpenAPI support in ASP.NET Core API apps
1113

1214
[!INCLUDE[](~/includes/not-latest-version.md)]
1315

14-
:::moniker range=">= aspnetcore-9.0"
16+
:::moniker range=">= aspnetcore-10.0"
1517

16-
ASP.NET Core supports the generation of OpenAPI documents in controller-based and Minimal APIs apps.
17-
The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) is a programming language-agnostic standard for documenting HTTP APIs. This standard is supported in ASP.NET Core apps through a combination of built-in APIs and open-source libraries. There are three key aspects to OpenAPI integration in an application:
18+
ASP.NET Core supports the generation of OpenAPI documents in controller-based and Minimal API apps.
19+
The [OpenAPI specification](https://spec.openapis.org/oas/latest.html) is a programming language-agnostic standard for documenting HTTP APIs. ASP.NET Core apps support this standard through a combination of built-in APIs and open-source libraries. There are three key aspects to OpenAPI integration in an application:
1820

1921
* Generating information about the endpoints in the app.
2022
* Gathering the information into a format that matches the OpenAPI schema.
21-
* Exposing the generated OpenAPI document via a visual UI or a serialized file.
22-
23-
ASP.NET Core apps provide built-in support for generating information about endpoints in an app via the `Microsoft.AspNetCore.OpenApi` package.
23+
* Exposing the generated OpenAPI document through a visual UI or a serialized file.
2424

25-
<!-- TODO: Merge content from controllers overview here, as appropriate -->
25+
ASP.NET Core provides first-party support for generating information about endpoints in an app through the `Microsoft.AspNetCore.OpenApi` package.
2626

27-
The following code is generated by the ASP.NET Core minimal web API template and uses OpenAPI:
27+
The ASP.NET Core minimal web API template generates the following code that uses OpenAPI:
2828

29-
[!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_default&highlight=5,9-12)]
29+
[!code-csharp[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/Program.cs?name=snippet_default&highlight=5,9-12)]
3030

3131
In the preceding highlighted code:
3232

@@ -39,25 +39,25 @@ In the preceding highlighted code:
3939

4040
The [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi/) package provides the following features:
4141

42-
* Support for generating OpenAPI documents at run time and accessing them via an endpoint on the application.
43-
* Support for "transformer" APIs that allow modifying the generated document.
42+
* Support for generating OpenAPI documents at runtime and accessing them through an endpoint on the application.
43+
* Support for "transformer" APIs that modify the generated document.
4444

4545
To use the `Microsoft.AspNetCore.OpenApi` package, add it as a PackageReference to a project file:
4646

47-
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=15)]
47+
[!code-xml[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/projectFile.xml?highlight=15)]
4848

4949
To learn more about the `Microsoft.AspNetCore.OpenApi` package, see <xref:fundamentals/openapi/aspnetcore-openapi>.
5050

5151
## `Microsoft.Extensions.ApiDescription.Server` NuGet package
5252

53-
The [`Microsoft.Extensions.ApiDescription.Server`](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server/) package provides support for generating OpenAPI documents at build time and serializing them.
53+
The [`Microsoft.Extensions.ApiDescription.Server`](https://www.nuget.org/packages/Microsoft.Extensions.ApiDescription.Server/) package supports generating OpenAPI documents at build time and serializing them.
5454

5555
To use `Microsoft.Extensions.ApiDescription.Server`, add it as a PackageReference to a project file.
56-
Document generation at build time is enabled by setting the `OpenApiGenerateDocuments` property.
56+
Enable document generation at build time by setting the `OpenApiGenerateDocuments` property.
5757
By default, the generated OpenAPI document is saved to the `obj` directory, but you can customize
5858
the output directory by setting the `OpenApiDocumentsDirectory` property.
5959

60-
[!code-xml[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)]
60+
[!code-xml[](~/fundamentals/openapi/samples/10.x/WebMinOpenApi/projectFile.xml?highlight=9-12,16-19)]
6161

6262
<!-- Include makes it trivial to move this anywhere in the doc OR add to other docs-->
6363
[!INCLUDE[](~/fundamentals/openapi/includes/api_endpoint_operation.md)]
@@ -74,4 +74,5 @@ the output directory by setting the `OpenApiDocumentsDirectory` property.
7474

7575
:::moniker-end
7676

77-
[!INCLUDE[](~/fundamentals/openapi/includes/overview6-8.md)]
77+
[!INCLUDE[](~/fundamentals/openapi/includes/overview-6-8.md)]
78+
[!INCLUDE[](~/fundamentals/openapi/includes/overview-9.md)]

0 commit comments

Comments
 (0)