Migrate OpenAPI docs from Swashbuckle to Scalar

Directory.Packages.props

@@ -1,9 +1,9 @@
 <Project>
   <!-- Runtime -->
   <ItemGroup>
-    <PackageVersion Include="Asp.Versioning.Http" Version="10.0.0-preview.1" />
-    <PackageVersion Include="Asp.Versioning.Mvc" Version="10.0.0-preview.1" />
-    <PackageVersion Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.0.0-preview.1" />
+    <PackageVersion Include="Asp.Versioning.Http" Version="10.0.0-preview.2" />
+    <PackageVersion Include="Asp.Versioning.Mvc" Version="10.0.0-preview.2" />
+    <PackageVersion Include="Asp.Versioning.Mvc.ApiExplorer" Version="10.0.0-preview.2" />
     <PackageVersion Include="Azure.Core" Version="1.51.1" />
     <PackageVersion Include="DotNet.ReproducibleBuilds" Version="2.0.2" />
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.3" />
@@ -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>

README.md

@@ -88,7 +88,7 @@ For API Versioning support:
 dotnet add package ServiceLevelIndicators.Asp.ApiVersioning
 ```
 
-## Usage for Web API MVC
+## Usage for ASP.NET Core MVC
 
 1. Register SLI with open telemetry by calling `AddServiceLevelIndicatorInstrumentation`.
 
@@ -142,7 +142,7 @@ dotnet add package ServiceLevelIndicators.Asp.ApiVersioning
     app.UseServiceLevelIndicator();
     ```
 
-## Usage for Minimal API
+## Usage for Minimal APIs
 
 1. Register SLI with open telemetry by calling `AddServiceLevelIndicatorInstrumentation`.
 
@@ -186,7 +186,7 @@ dotnet add package ServiceLevelIndicators.Asp.ApiVersioning
        .AddServiceLevelIndicator();
     ```
 
-### Usage for background jobs
+## Usage for Background Jobs
 
 You can measure a block of code by wrapping it in a `using` clause of `MeasuredOperation`.
 
@@ -201,14 +201,16 @@ async Task MeasureCodeBlock(ServiceLevelIndicator serviceLevelIndicator)
 }
 ```
 
-### Customizations
+## Operational Guidance
 
-### Cardinality guidance
+### Cardinality Guidance
 
 Metric dimensions should stay bounded. `CustomerResourceId` and values captured with `[Measure]` are useful when they represent a stable tenant, customer group, plan, environment, or region, but they become expensive if you feed them raw per-user or highly variable values.
 
 Prefer values with a controlled set of outcomes. Avoid using email addresses, request IDs, timestamps, or unconstrained free text unless your metrics backend is explicitly designed for high-cardinality telemetry.
 
+## ASP.NET Core Customizations
+
 Once the Prerequisites are done, all controllers will emit SLI information.
 The default operation name is in the format <HTTP Method> <Controller>/<Action>.
 eg GET WeatherForecast/Action1
@@ -316,25 +318,16 @@ eg GET WeatherForecast/Action1
 - To prevent automatically emitting SLI information on all controllers, set the option,
 
     ``` csharp
-    ServiceLevelIndicatorOptions.AutomaticallyEmitted = false;
+    builder.Services.AddServiceLevelIndicator(options =>
+    {
+        options.AutomaticallyEmitted = false;
+    })
+    .AddMvc();
     ```
 
     In this case, add the attribute `[ServiceLevelIndicator]` on the controllers that should emit SLI.
 
-- To measure a process, run it within a `using StartMeasuring` block.
-
-   Example:
-
-    ```csharp
-    public void StoreItem(MyDomainEvent domainEvent)
-    {
-        var attribute = new KeyValuePair<string, object?>("Event", domainEvent.GetType().Name);
-        using var measuredOperation = _serviceLevelIndicator.StartMeasuring("StoreItem", attribute);
-        DoTheWork();
-    }
-    ```
-
-### Sample
+## Sample
 
 Try out the sample weather forecast Web API.
 

ServiceLevelIndicators/src/README.md

@@ -43,22 +43,26 @@ builder.Services.AddOpenTelemetry()
         metrics.AddOtlpExporter();
     });
 
-builder.Services.AddServiceLevelIndicator(options =>
+builder.Services.Configure<ServiceLevelIndicatorOptions>(options =>
 {
     options.Meter = sliMeter;
     options.LocationId = ServiceLevelIndicator.CreateLocationId("public", "westus3");
     options.CustomerResourceId = "my-customer";
 });
+
+builder.Services.AddSingleton<ServiceLevelIndicator>();
 ```
 
 ### 2. Configure options
 
 ```csharp
-builder.Services.AddServiceLevelIndicator(options =>
+builder.Services.Configure<ServiceLevelIndicatorOptions>(options =>
 {
     options.LocationId = ServiceLevelIndicator.CreateLocationId("public", "westus3");
     options.CustomerResourceId = "my-customer";
 });
+
+builder.Services.AddSingleton<ServiceLevelIndicator>();
 ```
 
 ### 3. Measure operations

docs/usage-reference.md

@@ -48,11 +48,13 @@ builder.Services.AddOpenTelemetry()
 Register the service:
 
 ```csharp
-builder.Services.AddServiceLevelIndicator(options =>
+builder.Services.Configure<ServiceLevelIndicatorOptions>(options =>
 {
     options.LocationId = ServiceLevelIndicator.CreateLocationId("public", "westus3");
     options.CustomerResourceId = "tenant-a";
 });
+
+builder.Services.AddSingleton<ServiceLevelIndicator>();
 ```
 
 Measure work:
@@ -89,12 +91,14 @@ builder.Services.AddOpenTelemetry()
         metrics.AddOtlpExporter();
     });
 
-builder.Services.AddServiceLevelIndicator(options =>
+builder.Services.Configure<ServiceLevelIndicatorOptions>(options =>
 {
     options.Meter = sliMeter;
     options.LocationId = ServiceLevelIndicator.CreateLocationId("public", "westus3");
     options.CustomerResourceId = "tenant-a";
 });
+
+builder.Services.AddSingleton<ServiceLevelIndicator>();
 ```
 
 Available registration overloads:

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" />