diff --git a/docs/usage/openapi-documentation.md b/docs/usage/openapi-documentation.md index 2e0af9340d..d3cbdffa90 100644 --- a/docs/usage/openapi-documentation.md +++ b/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:/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. diff --git a/package-versions.props b/package-versions.props index 1700f2b66d..be2fc8dd86 100644 --- a/package-versions.props +++ b/package-versions.props @@ -22,6 +22,7 @@ 9.0.* 14.2.* 13.0.* + 1.2.* 8.0.* 7.*-* 9.0.* diff --git a/src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj b/src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj index bf0dce1b3c..768a2de827 100644 --- a/src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj +++ b/src/Examples/JsonApiDotNetCoreExample/JsonApiDotNetCoreExample.csproj @@ -18,6 +18,8 @@ + + diff --git a/src/Examples/JsonApiDotNetCoreExample/Program.cs b/src/Examples/JsonApiDotNetCoreExample/Program.cs index b8b33505cf..56448b271e 100644 --- a/src/Examples/JsonApiDotNetCoreExample/Program.cs +++ b/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(); }