Add docs on Microsoft.AspNetCore.OpenApi

aspnetcore/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/.spectral.yaml

@@ -0,0 +1 @@
+extends: ["spectral:oas"]

aspnetcore/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/Program.cs

@@ -1,7 +1,6 @@
-#define DEFAULT // DEFAULT
-#if NEVER
-#elif DEFAULT
-#region snippet
+#define SWAGGERUI
+
+#if DEFAULT
 using Microsoft.AspNetCore.OpenApi;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -42,5 +41,211 @@ internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary
 {
     public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
 }
-#endregion
+#endif
+
+#if DOCUMENTtransformer1
+// <snippet_documenttransformer1>
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.AspNetCore.Builder;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddOpenApi(options =>
+{
+    options.UseTransformer((document, context, cancellationToken) =>
+    {
+        document.Info = new()
+        {
+            Title = "Checkout API",
+            Version = "v1",
+            Description = "API for processing checkouts from cart."
+        };
+        return Task.CompletedTask;
+    });
+});
+
+var app = builder.Build();
+
+app.MapOpenApi();
+
+app.MapGet("/", () => "Hello world!");
+
+app.Run();
+// </snippet_documenttransformer1>
+#endif
+
+#if DOCUMENTtransformer2
+// <snippet_documenttransformer2>
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.OpenApi.Models;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddAuthentication().AddJwtBearer();
+
+builder.Services.AddOpenApi(options =>
+{
+    options.UseTransformer<BearerSecuritySchemeTransformer>();
+});
+
+var app = builder.Build();
+
+app.MapOpenApi();
+
+app.MapGet("/", () => "Hello world!");
+
+app.Run();
+
+internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
+{
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
+        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
+        {
+            var requirements = new Dictionary<string, OpenApiSecurityScheme>
+            {
+                ["Bearer"] = new OpenApiSecurityScheme
+                {
+                    Type = SecuritySchemeType.Http,
+                    Scheme = "bearer", // "bearer" refers to the header name here
+                    In = ParameterLocation.Header,
+                    BearerFormat = "Json Web Token"
+                }
+            };
+            document.Components ??= new OpenApiComponents();
+            document.Components.SecuritySchemes = requirements;
+        }
+    }
+}
+// </snippet_documenttransformer2>
+#endif
+
+#if OPERATIONtransformer1
+// <snippet_operationtransformer1>
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.OpenApi.Models;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddAuthentication().AddJwtBearer();
+
+builder.Services.AddOpenApi(options =>
+{
+    options.UseOperationTransformer((operation, context, cancellationToken) =>
+    {
+        operation.Responses.Add("500", new OpenApiResponse { Description = "Internal server error" });
+        return Task.CompletedTask;
+    });
+});
+
+var app = builder.Build();
+
+app.MapOpenApi();
+
+app.MapGet("/", () => "Hello world!");
+
+app.Run();
+// </snippet_operationtransformer1>
+#endif
+
+#if MULTIDOC_OPERATIONtransformer1
+// <snippet_multidoc_operationtransformer1>
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.OpenApi.Models;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddAuthentication().AddJwtBearer();
+
+builder.Services.AddOpenApi("internal", options =>
+{
+    options.UseTransformer<BearerSecuritySchemeTransformer>();
+});
+builder.Services.AddOpenApi("public");
+
+var app = builder.Build();
+
+app.MapOpenApi();
+
+app.MapGet("/world", () => "Hello world!")
+    .WithGroupName("internal");
+app.MapGet("/", () => "Hello universe!")
+    .WithGroupName("public");
+
+app.Run();
+
+internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
+{
+    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
+    {
+        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
+        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
+        {
+            // Add the security scheme at the document level
+            var requirements = new Dictionary<string, OpenApiSecurityScheme>
+            {
+                ["Bearer"] = new OpenApiSecurityScheme
+                {
+                    Type = SecuritySchemeType.Http,
+                    Scheme = "bearer", // "bearer" refers to the header name here
+                    In = ParameterLocation.Header,
+                    BearerFormat = "Json Web Token"
+                }
+            };
+            document.Components ??= new OpenApiComponents();
+            document.Components.SecuritySchemes = requirements;
+
+            // Apply it as a requirement for all operations
+            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
+            {
+                operation.Value.Security.Add(new OpenApiSecurityRequirement
+                {
+                    [new OpenApiSecurityScheme { Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme } }] = Array.Empty<string>()
+                });
+            }
+        }
+    }
+}
+
+// </snippet_multidoc_operationtransformer2>
+#endif
+
+#if SWAGGERUI
+// <snippet_swaggerui>
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.OpenApi;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.OpenApi.Models;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+app.MapOpenApi();
+if (app.Environment.IsDevelopment())
+{
+    app.UseSwaggerUI(options =>
+    {
+        options.SwaggerEndpoint("/openapi/v1.json", "v1");
+    });
+
+}
+
+app.MapGet("/", () => "Hello world!");
+
+app.Run();
+// </snippet_swaggerui>
 #endif

aspnetcore/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/WebMinOpenApi.csproj

@@ -6,8 +6,19 @@
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
+    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
+  </PropertyGroup>
+
   <ItemGroup>
-    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*-*" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0-preview.5.24257.1" />
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.0-preview.5.24257.1" />
+    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.0-preview.5.24257.1">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUi" Version="6.5.0" />
   </ItemGroup>
 
 </Project>

aspnetcore/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/WebMinOpenApi.json

@@ -0,0 +1,34 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "GetDocument.Insider | v1",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/": {
+      "get": {
+        "tags": [
+          "GetDocument.Insider"
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "x-aspnetcore-id": "12a849de-622a-4fe0-a605-a5ea17254453"
+      }
+    }
+  },
+  "tags": [
+    {
+      "name": "GetDocument.Insider"
+    }
+  ]
+}

aspnetcore/fundamentals/minimal-apis/9.0-samples/WebMinOpenApi/nuget.config

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <!--To inherit the global NuGet package sources remove the <clear/> line below -->
+    <clear />
+    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
+    <add key="dotnet9" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet9/nuget/v3/index.json" />
+  </packageSources>
+</configuration>