Migrate OpenAPI docs from Swashbuckle to Scalar

.github/copilot-instructions.md

@@ -3,4 +3,4 @@
 ## Package Constraints
 
 - **FluentAssertions**: Do not upgrade beyond major version 7.x due to a licensing change in version 8+.
-- **Swashbuckle.AspNetCore**: Do not upgrade beyond version 6.x due to breaking changes in Microsoft.OpenApi v2.
+

Directory.Packages.props

@@ -17,7 +17,7 @@
     <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.15.0" />
     <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.15.0" />
     <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.15.0" />
-    <PackageVersion Include="Swashbuckle.AspNetCore" Version="6.8.1" />
+    <PackageVersion Include="Scalar.AspNetCore" Version="2.13.0" />
   </ItemGroup>
   <!-- Test -->
   <ItemGroup>

sample/MinApi/Program.cs

@@ -1,6 +1,7 @@
 using Azure.Core;
 using OpenTelemetry.Metrics;
 using OpenTelemetry.Resources;
+using Scalar.AspNetCore;
 using SampleMinimalApiSli;
 using ServiceLevelIndicators;
 
@@ -13,14 +14,7 @@
     "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
 };
 
-builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen(options =>
-{
-
-    var fileName = typeof(Program).Assembly.GetName().Name + ".xml";
-    var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
-    options.IncludeXmlComments(filePath);
-});
+builder.Services.AddOpenApi();
 
 // Build a resource configuration action to set service information.
 
@@ -65,8 +59,8 @@
    .AddServiceLevelIndicator("background_work");
 
 app.UseUserRoute();
-app.UseSwagger();
-app.UseSwaggerUI();
+app.MapOpenApi();
+app.MapScalarApiReference();
 app.UseHttpsRedirection();
 app.UseServiceLevelIndicator();
 app.Run();

sample/MinApi/Properties/launchSettings.json

@@ -3,7 +3,7 @@
     "SampleMinimalApiSli": {
       "commandName": "Project",
       "launchBrowser": true,
-      "launchUrl": "swagger",
+      "launchUrl": "scalar/v1",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       },

sample/MinApi/SampleMinimalApiSli.csproj

@@ -7,7 +7,8 @@
     <PackageReference Include="Azure.Core" />
     <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
     <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
-    <PackageReference Include="Swashbuckle.AspNetCore" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
+    <PackageReference Include="Scalar.AspNetCore" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\ServiceLevelIndicators.Asp\src\ServiceLevelIndicators.Asp.csproj" />

sample/WebApi/Program.cs

@@ -3,6 +3,7 @@
 using Microsoft.Extensions.Options;
 using OpenTelemetry.Metrics;
 using OpenTelemetry.Resources;
+using Scalar.AspNetCore;
 using SampleWebApplicationSLI;
 using ServiceLevelIndicators;
 
@@ -13,13 +14,7 @@
 builder.Services.AddControllers();
 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
 builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddSwaggerGen(options =>
-{
-
-    var fileName = typeof(Program).Assembly.GetName().Name + ".xml";
-    var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
-    options.IncludeXmlComments(filePath);
-});
+builder.Services.AddOpenApi();
 builder.Services.AddProblemDetails();
 
 // Build a resource configuration action to set service information.
@@ -47,8 +42,8 @@
 
 var app = builder.Build();
 
-app.UseSwagger();
-app.UseSwaggerUI();
+app.MapOpenApi();
+app.MapScalarApiReference();
 app.UseHttpsRedirection();
 app.UseServiceLevelIndicator();
 app.UseAuthorization();

sample/WebApi/Properties/launchSettings.json

@@ -3,7 +3,7 @@
     "SampleWebApplicationSLI": {
       "commandName": "Project",
       "launchBrowser": true,
-      "launchUrl": "swagger",
+      "launchUrl": "scalar/v1",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       },

sample/WebApi/SampleWebApplicationSLI.csproj

@@ -7,7 +7,8 @@
     <PackageReference Include="Azure.Core" />
     <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
     <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
-    <PackageReference Include="Swashbuckle.AspNetCore" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
+    <PackageReference Include="Scalar.AspNetCore" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\ServiceLevelIndicators.Asp\src\ServiceLevelIndicators.Asp.csproj" />

sample/WebApiVersioned/Program.cs

@@ -1,31 +1,15 @@
 using Azure.Core;
-using Microsoft.Extensions.Options;
 using OpenTelemetry.Metrics;
 using OpenTelemetry.Resources;
-using SampleVersionedWebApplicationSLI;
+using Scalar.AspNetCore;
 using ServiceLevelIndicators;
-using Swashbuckle.AspNetCore.SwaggerGen;
 
 var builder = WebApplication.CreateBuilder(args);
 
 // Add services to the container.
 
 builder.Services.AddControllers();
-// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
-builder.Services.AddEndpointsApiExplorer();
-builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerDefaultOptions>();
-builder.Services.AddSwaggerGen(
-            options =>
-            {
-                // add a custom operation filter which sets default values
-                options.OperationFilter<AddApiVersionMetadata>();
-
-                var fileName = typeof(Program).Assembly.GetName().Name + ".xml";
-                var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
-
-                // integrate XML comments
-                options.IncludeXmlComments(filePath);
-            });
+builder.Services.AddOpenApi();
 builder.Services.AddApiVersioning()
         .AddMvc()
         .AddApiExplorer();
@@ -49,21 +33,10 @@
 
 var app = builder.Build();
 
-app.UseSwagger();
-app.UseSwaggerUI(
-    options =>
-    {
-        options.RoutePrefix = string.Empty; // make home page the swagger UI
-        var descriptions = app.DescribeApiVersions();
-
-        // build a swagger endpoint for each discovered API version
-        foreach (var description in descriptions)
-        {
-            var url = $"/swagger/{description.GroupName}/swagger.json";
-            var name = description.GroupName.ToUpperInvariant();
-            options.SwaggerEndpoint(url, name);
-        }
-    });
+// TODO: Use .AddOpenApi() from Asp.Versioning.OpenApi with WithDocumentPerVersion()
+// and AddScalarTransformers() once a stable release is available.
+app.MapOpenApi();
+app.MapScalarApiReference();
 
 // Random delay.
 Random rnd = new Random();

sample/WebApiVersioned/Properties/launchSettings.json

@@ -3,6 +3,7 @@
     "SampleVersionedWebApplicationSLI": {
       "commandName": "Project",
       "launchBrowser": true,
+      "launchUrl": "scalar/v1",
       "environmentVariables": {
         "ASPNETCORE_ENVIRONMENT": "Development"
       },

sample/WebApiVersioned/SampleVersionedWebApplicationSLI.csproj

@@ -9,7 +9,8 @@
     <PackageReference Include="Azure.Core" />
     <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
     <PackageReference Include="OpenTelemetry.Extensions.Hosting" />
-    <PackageReference Include="Swashbuckle.AspNetCore" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
+    <PackageReference Include="Scalar.AspNetCore" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\ServiceLevelIndicators.Asp.ApiVersioning\src\ServiceLevelIndicators.Asp.ApiVersioning.csproj" />