Skip to content

Replace Swagger UI with Scalar #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

Replace Swagger UI with Scalar #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
866e52a
Initial plan
Copilot Dec 20, 2025
17b8552
Replace Swagger UI with Scalar for API documentation
Copilot Dec 20, 2025
057134b
Address code review feedback - update comment terminology
Copilot Dec 20, 2025
983c474
Update README to document Scalar API documentation
Copilot Dec 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Api/src/Api.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" />
<PackageReference Include="OpenTelemetry.Extensions.Hosting" />
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" />
<PackageReference Include="Scalar.AspNetCore" />
<PackageReference Include="ServiceLevelIndicators.Asp.ApiVersioning" />
<PackageReference Include="Swashbuckle.AspNetCore" />
</ItemGroup>
Expand Down
7 changes: 4 additions & 3 deletions Api/src/ConfigureSwaggerOptions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@
/// <summary>
/// Configure the Swashbuckle options, which defines the document endpoints and high-level documentation (e.g. description)
/// </summary>
/// <remarks>This allows API versioning to define a Swagger document per API version after the
/// <see cref="IApiVersionDescriptionProvider"/> service has been resolved from the service container.</remarks>
/// <remarks>This allows API versioning to define an OpenAPI document per API version after the
/// <see cref="IApiVersionDescriptionProvider"/> service has been resolved from the service container.
/// These documents are consumed by Scalar for API documentation.</remarks>
public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
{
private readonly IApiVersionDescriptionProvider provider;
Expand All @@ -36,7 +37,7 @@ public void Configure(SwaggerGenOptions options)

private static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
{
var text = new StringBuilder("An example application with OpenAPI, Swashbuckle, and API versioning.");
var text = new StringBuilder("An example application with OpenAPI, Scalar, and API versioning.");
var info = new OpenApiInfo()
{
Title = "Best Weather forecast API",
Expand Down
26 changes: 12 additions & 14 deletions Api/src/Program.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
using BestWeatherForecast.Api;
using BestWeatherForecast.Api.Middleware;
using BestWeatherForecast.Application;
using Scalar.AspNetCore;
using ServiceLevelIndicators;

var builder = WebApplication.CreateBuilder(args);
Expand All @@ -17,21 +18,18 @@

if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(
options =>
app.MapSwagger("/openapi/{documentName}.json");
app.MapScalarApiReference(options =>
{
options.WithTitle("Best Weather Forecast API");
var descriptions = app.DescribeApiVersions();

// Add all API version documents to Scalar
foreach (var description in descriptions)
{
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);
}
});
options.AddDocument(description.GroupName, $"/openapi/{description.GroupName}.json");
}
});
}

app.UseHttpsRedirection();
Expand Down
1 change: 1 addition & 0 deletions Directory.Packages.props
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
<PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.14.0" />
<PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.14.0" />
<PackageVersion Include="ServiceLevelIndicators.Asp.ApiVersioning" Version="8.0.1" />
<PackageVersion Include="Scalar.AspNetCore" Version="2.11.8" />
<PackageVersion Include="Swashbuckle.AspNetCore" Version="10.1.0" />
<PackageVersion Include="System.Text.Json" Version="10.0.1" />
</ItemGroup>
Expand Down
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,12 @@ Here is a more elaborate sample code [BuberDinner](https://github.com/xavierjohn
To get started with this template, All you need to do is download the repository to your local development environment, rename it to your project and use it. This template comes with all layers already implemented along with the Unit Tests in place.
This is not a Visual Studio project template.

### API Documentation

The template uses [Scalar](https://github.com/scalar/scalar) for interactive API documentation. When running in development mode, you can access the API documentation at `/scalar` which provides a modern, developer-friendly interface for exploring and testing your API endpoints.

The documentation is automatically generated from OpenAPI specifications and supports API versioning out of the box.

## Lets talk a little bit more about the layers implemented in the Template

### Domain Layer
Expand Down