From 866e52a317caa97962588b7d9c5d52a653297766 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:39:26 +0000 Subject: [PATCH 1/4] Initial plan From 17b855260f42790abc889b3d04686e853a8943fa Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:55:42 +0000 Subject: [PATCH 2/4] Replace Swagger UI with Scalar for API documentation Co-authored-by: xavierjohn <1859710+xavierjohn@users.noreply.github.com> --- Api/src/Api.csproj | 1 + Api/src/ConfigureSwaggerOptions.cs | 7 ++++--- Api/src/Program.cs | 26 ++++++++++++-------------- Directory.Packages.props | 1 + 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/Api/src/Api.csproj b/Api/src/Api.csproj index cd894b2..19578d6 100644 --- a/Api/src/Api.csproj +++ b/Api/src/Api.csproj @@ -12,6 +12,7 @@ + diff --git a/Api/src/ConfigureSwaggerOptions.cs b/Api/src/ConfigureSwaggerOptions.cs index 1667155..528f64b 100644 --- a/Api/src/ConfigureSwaggerOptions.cs +++ b/Api/src/ConfigureSwaggerOptions.cs @@ -11,8 +11,9 @@ /// /// Configure the Swashbuckle options, which defines the document endpoints and high-level documentation (e.g. description) /// -/// This allows API versioning to define a Swagger document per API version after the -/// service has been resolved from the service container. +/// This allows API versioning to define a Swagger/OpenAPI document per API version after the +/// service has been resolved from the service container. +/// These documents are consumed by Scalar for API documentation. public class ConfigureSwaggerOptions : IConfigureOptions { private readonly IApiVersionDescriptionProvider provider; @@ -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", diff --git a/Api/src/Program.cs b/Api/src/Program.cs index 80ec165..08aea76 100644 --- a/Api/src/Program.cs +++ b/Api/src/Program.cs @@ -2,6 +2,7 @@ using BestWeatherForecast.Api; using BestWeatherForecast.Api.Middleware; using BestWeatherForecast.Application; +using Scalar.AspNetCore; using ServiceLevelIndicators; var builder = WebApplication.CreateBuilder(args); @@ -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(); diff --git a/Directory.Packages.props b/Directory.Packages.props index caf7b23..50cadd2 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -29,6 +29,7 @@ + From 057134b0802fe386574106de0e3abeec69d5c729 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:57:18 +0000 Subject: [PATCH 3/4] Address code review feedback - update comment terminology Co-authored-by: xavierjohn <1859710+xavierjohn@users.noreply.github.com> --- Api/src/ConfigureSwaggerOptions.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Api/src/ConfigureSwaggerOptions.cs b/Api/src/ConfigureSwaggerOptions.cs index 528f64b..7ae6414 100644 --- a/Api/src/ConfigureSwaggerOptions.cs +++ b/Api/src/ConfigureSwaggerOptions.cs @@ -11,7 +11,7 @@ /// /// Configure the Swashbuckle options, which defines the document endpoints and high-level documentation (e.g. description) /// -/// This allows API versioning to define a Swagger/OpenAPI document per API version after the +/// This allows API versioning to define an OpenAPI document per API version after the /// service has been resolved from the service container. /// These documents are consumed by Scalar for API documentation. public class ConfigureSwaggerOptions : IConfigureOptions From 983c474f4feed53734c760f722b04d2bee7e464b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 20 Dec 2025 19:00:44 +0000 Subject: [PATCH 4/4] Update README to document Scalar API documentation Co-authored-by: xavierjohn <1859710+xavierjohn@users.noreply.github.com> --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 4363b40..a46b79e 100644 --- a/README.md +++ b/README.md @@ -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