Add examples to AddOpenApi extension method/overloads (#58808)

* Add examples to AddOpenApi extension method/overloads
* Commit suggestions from PR review

Co-authored-by: Safia Abdalla <[email protected]>

src/OpenApi/src/Extensions/OpenApiServiceCollectionExtensions.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Http.Json;
 using Microsoft.AspNetCore.OpenApi;
 using Microsoft.Extensions.ApiDescriptions;
@@ -19,6 +20,14 @@ public static class OpenApiServiceCollectionExtensions
     /// </summary>
     /// <param name="services">The <see cref="IServiceCollection"/> to register services onto.</param>
     /// <param name="documentName">The name of the OpenAPI document associated with registered services.</param>
+    /// <example>
+    /// This method is commonly used to add OpenAPI services to the <see cref="WebApplicationBuilder.Services"/>
+    /// of a <see cref="WebApplicationBuilder"/>, as shown in the following example:
+    /// <code>
+    /// var builder = WebApplication.CreateBuilder(args);
+    /// builder.Services.AddOpenApi("MyWebApi");
+    /// </code>
+    /// </example>
     public static IServiceCollection AddOpenApi(this IServiceCollection services, string documentName)
     {
         ArgumentNullException.ThrowIfNull(services);
@@ -32,6 +41,17 @@ public static IServiceCollection AddOpenApi(this IServiceCollection services, st
     /// <param name="services">The <see cref="IServiceCollection"/> to register services onto.</param>
     /// <param name="documentName">The name of the OpenAPI document associated with registered services.</param>
     /// <param name="configureOptions">A delegate used to configure the target <see cref="OpenApiOptions"/>.</param>
+    /// <example>
+    /// This method is commonly used to add OpenAPI services to the <see cref="WebApplicationBuilder.Services"/>
+    /// of a <see cref="WebApplicationBuilder"/>, as shown in the following example:
+    /// <code>
+    /// var builder = WebApplication.CreateBuilder(args);
+    /// builder.Services.AddOpenApi("MyWebApi", options => {
+    ///     // Add a custom schema transformer for decimal types
+    ///     options.AddSchemaTransformer(DecimalTransformer.TransformAsync);
+    /// });
+    /// </code>
+    /// </example>
     public static IServiceCollection AddOpenApi(this IServiceCollection services, string documentName, Action<OpenApiOptions> configureOptions)
     {
         ArgumentNullException.ThrowIfNull(services);
@@ -51,13 +71,32 @@ public static IServiceCollection AddOpenApi(this IServiceCollection services, st
     /// </summary>
     /// <param name="services">The <see cref="IServiceCollection"/> to register services onto.</param>
     /// <param name="configureOptions">A delegate used to configure the target <see cref="OpenApiOptions"/>.</param>
+    /// <example>
+    /// This method is commonly used to add OpenAPI services to the <see cref="WebApplicationBuilder.Services"/>
+    /// of a <see cref="WebApplicationBuilder"/>, as shown in the following example:
+    /// <code>
+    /// var builder = WebApplication.CreateBuilder(args);
+    /// builder.Services.AddOpenApi(options => {
+    ///     // Add a custom schema transformer for decimal types
+    ///     options.AddSchemaTransformer(DecimalTransformer.TransformAsync);
+    /// });
+    /// </code>
+    /// </example>
     public static IServiceCollection AddOpenApi(this IServiceCollection services, Action<OpenApiOptions> configureOptions)
             => services.AddOpenApi(OpenApiConstants.DefaultDocumentName, configureOptions);
 
     /// <summary>
     /// Adds OpenAPI services related to the default document to the specified <see cref="IServiceCollection"/>.
     /// </summary>
     /// <param name="services">The <see cref="IServiceCollection"/> to register services onto.</param>
+    /// <example>
+    /// This method is commonly used to add OpenAPI services to the <see cref="WebApplicationBuilder.Services"/>
+    /// of a <see cref="WebApplicationBuilder"/>, as shown in the following example:
+    /// <code>
+    /// var builder = WebApplication.CreateBuilder(args);
+    /// builder.Services.AddOpenApi();
+    /// </code>
+    /// </example>
     public static IServiceCollection AddOpenApi(this IServiceCollection services)
         => services.AddOpenApi(OpenApiConstants.DefaultDocumentName);
 

src/OpenApi/src/Microsoft.AspNetCore.OpenApi.csproj

@@ -20,6 +20,7 @@
     <Reference Include="Microsoft.AspNetCore.Routing" />
     <Reference Include="Microsoft.AspNetCore.Mvc.Core" />
     <Reference Include="Microsoft.AspNetCore.Mvc.ApiExplorer" />
+    <Reference Include="Microsoft.AspNetCore" />
   </ItemGroup>
 
   <ItemGroup>