OpenAPI: Update tools for generating documentation website (#1661)

Author: bkoelman

docs/usage/openapi-documentation.md

@@ -1,20 +1,45 @@
 # OpenAPI documentation
 
-After [enabling OpenAPI](~/usage/openapi.md), you can expose a documentation website with SwaggerUI or Redoc.
+After [enabling OpenAPI](~/usage/openapi.md), you can expose a documentation website with SwaggerUI, Redoc and/or Scalar.
 
-### SwaggerUI
+## SwaggerUI
 
-Swashbuckle ships with [SwaggerUI](https://swagger.io/tools/swagger-ui/), which enables to visualize and interact with the JSON:API endpoints through a web page.
-This can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Program.cs` file:
+[SwaggerUI](https://swagger.io/tools/swagger-ui/) enables to visualize and interact with the JSON:API endpoints through a web page.
+While it conveniently provides the ability to execute requests, it doesn't show properties of derived types when component schema inheritance is used.
+
+SwaggerUI can be enabled by installing the `Swashbuckle.AspNetCore.SwaggerUI` NuGet package and adding the following to your `Program.cs` file:
 
 ```c#
 app.UseSwaggerUI();
 ```
 
-By default, SwaggerUI will be available at `http://localhost:<port>/swagger`.
+Then run your app and open `/swagger` in your browser.
 
-### Redoc
+## Redoc
 
 [Redoc](https://github.com/Redocly/redoc) is another popular tool that generates a documentation website from an OpenAPI document.
 It lists the endpoints and their schemas, but doesn't provide the ability to execute requests.
+However, this tool most accurately reflects properties when component schema inheritance is used; choosing a different "type" from the
+dropdown box dynamically adapts the list of schema properties.
+
 The `Swashbuckle.AspNetCore.ReDoc` NuGet package provides integration with Swashbuckle.
+After installing the package, add the following to your `Program.cs` file:
+
+```c#
+app.UseReDoc();
+```
+
+Next, run your app and navigate to `/api-docs` to view the documentation.
+
+## Scalar
+
+[Scalar](https://scalar.com/) is a modern documentation website generator, which includes the ability to execute requests.
+It shows component schemas in a low-level way (not collapsing `allOf` nodes), but does a poor job in handling component schema inheritance.
+
+After installing the `Scalar.AspNetCore` NuGet package, add the following to your `Program.cs` to make it use the OpenAPI document produced by Swashbuckle:
+
+```c#
+app.MapScalarApiReference(options => options.OpenApiRoutePattern = "/swagger/{documentName}/swagger.json");
+```
+
+Then run your app and navigate to `/scalar/v1` to view the documentation.

package-versions.props

@@ -22,6 +22,7 @@
     <MicrosoftApiServerVersion>9.0.*</MicrosoftApiServerVersion>
     <NSwagApiClientVersion>14.2.*</NSwagApiClientVersion>
     <NewtonsoftJsonVersion>13.0.*</NewtonsoftJsonVersion>
+    <ScalarAspNetCoreVersion>1.2.*</ScalarAspNetCoreVersion>
     <SourceLinkVersion>8.0.*</SourceLinkVersion>
     <SwashbuckleVersion>7.*-*</SwashbuckleVersion>
     <SystemTextJsonVersion>9.0.*</SystemTextJsonVersion>

src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj

@@ -18,6 +18,8 @@
     <PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="$(EntityFrameworkCoreVersion)" />
     <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="$(MicrosoftApiServerVersion)" PrivateAssets="all" />
     <PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="$(EntityFrameworkCoreVersion)" />
+    <PackageReference Include="Scalar.AspNetCore" Version="$(ScalarAspNetCoreVersion)" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="$(SwashbuckleVersion)" />
+    <PackageReference Include="Swashbuckle.AspNetCore.ReDoc" Version="$(SwashbuckleVersion)" />
   </ItemGroup>
 </Project>

src/Examples/JsonApiDotNetCoreExample/Program.cs

@@ -9,6 +9,7 @@
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Diagnostics;
 using Microsoft.Extensions.DependencyInjection.Extensions;
+using Scalar.AspNetCore;
 
 [assembly: ExcludeFromCodeCoverage]
 
@@ -103,6 +104,8 @@ static void ConfigurePipeline(WebApplication app)
 
     app.UseSwagger();
     app.UseSwaggerUI();
+    app.UseReDoc();
+    app.MapScalarApiReference(options => options.OpenApiRoutePattern = "/swagger/{documentName}/swagger.json");
 
     app.MapControllers();
 }