diff --git a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md index 9d10200bf2f3..fff1d7f5517f 100644 --- a/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md +++ b/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md @@ -5,7 +5,7 @@ description: Learn how to generate and customize OpenAPI documents in an ASP.NET ms.author: safia monikerRange: '>= aspnetcore-6.0' ms.custom: mvc -ms.date: 01/23/2025 +ms.date: 2/23/2025 uid: fundamentals/openapi/aspnetcore-openapi --- # Generate OpenAPI documents @@ -14,7 +14,7 @@ uid: fundamentals/openapi/aspnetcore-openapi The [`Microsoft.AspNetCore.OpenApi`](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi) package provides built-in support for OpenAPI document generation in ASP.NET Core. The package provides the following features: -* Support for generating OpenAPI documents at run time and accessing them via an endpoint on the application. +* Support for generating OpenAPI documents at run time and accessing them via an endpoint on the app. * Support for "transformer" APIs that allow modifying the generated document. * Support for generating multiple OpenAPI documents from a single app. * Takes advantage of JSON schema support provided by [`System.Text.Json`](/dotnet/api/system.text.json). @@ -112,7 +112,7 @@ The OpenAPI endpoint doesn't enable any authorization checks by default. Howeve #### Cache generated OpenAPI document -The OpenAPI document is regenerated every time a request to the OpenAPI endpoint is sent. Regeneration enables transformers to incorporate dynamic application 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. +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. [!code-csharp[](~/fundamentals/openapi/samples/9.x/WebMinOpenApi/Program.cs?name=snippet_mapopenapiwithcaching)] @@ -122,7 +122,7 @@ In some scenarios, it's helpful to generate multiple OpenAPI documents with diff * Generating OpenAPI documentation for different audiences, such as public and internal APIs. * Generating OpenAPI documentation for different versions of an API. -* Generating OpenAPI documentation for different parts of an application, such as a frontend and backend API. +* Generating OpenAPI documentation for different parts of an app, such as a frontend and backend API. To generate multiple OpenAPI documents, call the extension method once for each document, specifying a different document name in the first parameter each time. @@ -135,9 +135,12 @@ Each invocation of delegate method of to determine which endpoints to include in each document. -For each document, the delegate method is called for each endpoint in the application, passing the object for the endpoint. The method returns a boolean value indicating whether the endpoint should be included in the document. The object contains information about the endpoint, such as the HTTP method, route, and response types, as well as metadata attached to the endpoint via attributes or extension methods. +For each document, the delegate method is called for each endpoint in the app, passing the object for the endpoint. The method returns a boolean value indicating whether the endpoint should be included in the document. The object: -The default implementation of this delegate uses the field of , which is set on an endpoint using either the extension method or the attribute, to determine which endpoints to include in the document. Any endpoint that has not been assigned a group name is included all OpenAPI documents. +* contains information about the endpoint, such as the HTTP method, route, and response types +* Metadata attached to the endpoint via attributes or extension methods. + +The default implementation of this delegate uses the field of . The delegate is set on an endpoint using either the extension method or the attribute. `WithGroupName` or the `EndpointGroupName` attribute determines which endpoints to include in the document. Any endpoint that has not been assigned a group name is included all OpenAPI documents. ```csharp // Include endpoints without a group name or with a group name that matches the document name @@ -148,13 +151,13 @@ You can customize the @@ -198,7 +218,7 @@ The value of `OpenApiDocumentsDirectory` is resolved relative to the project fil #### Modifying the output file name -By default, the generated OpenAPI document will have the same name as the application's project file. To modify the name of the emitted file, set the `--file-name` argument in the `OpenApiGenerateDocumentsOptions` property. +By default, the generated OpenAPI document will have 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. ```xml @@ -208,7 +228,7 @@ By default, the generated OpenAPI document will have the same name as the applic #### Selecting the OpenAPI document to generate -Some applications may be configured to emit multiple OpenAPI documents, for various versions of an API or to distinguish between public and internal APIs. By default, the build-time document generator will emit files for all documents that are configured in an application. To only emit for a single document name, set the `--document-name` argument in the `OpenApiGenerateDocumentsOptions` property. +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. ```xml