Scalar Integration
Scalar has quickly become one of the more common, modern OpenAPI user interfaces and it easily integrates with API Versioning. The only thing you need to do is tell Scalar about the documents your application will generate.
Remember to add the necessary references to one or both of the following:
- Versioned OpenAPI Extensions for ASP.NET Core
- API Explorer Extensions for ASP.NET Core
- API Explorer Extensions for ASP.NET Core with gRPC
- API Explorer Extensions for ASP.NET Core with OData
- Scalar for ASP.NET Core
- Scalar for ASP.NET Core with Microsoft OpenAPI extensions
Minimal APIs
builder.Services.AddApiVersioning()
.AddApiExplorer()
.AddOpenApi( options => options.Document.AddScalarTransformers() );
Controllers
builder.Services.AddApiVersioning()
.AddMvc()
.AddApiExplorer()
.AddOpenApi( options => options.Document.AddScalarTransformers() );
gRPC
builder.Services.AddApiVersioning()
.AddApiExplorer()
.AddGrpc()
.AddGrpcApiExplorer()
.AddOpenApi( options => options.Document.AddScalarTransformers() );
OData
builder.Services.AddApiVersioning()
.AddOData()
.AddODataApiExplorer()
.AddOpenApi( options => options.Document.AddScalarTransformers() );
Once you have that configured, you need only generate an OpenAPI document per version and let Scalar know which generated documents it should expect.
app.MapOpenApi().WithDocumentPerVersion();
app.MapScalarApiReference(
options =>
{
var descriptions = app.DescribeApiVersions();
for ( var i = 0; i < descriptions.Count; i++ )
{
var description = descriptions[i];
var isDefault = i == descriptions.Count - 1;
options.AddDocument( description.GroupName, description.GroupName, isDefault: isDefault );
}
} );
Examples
There are end-to-end examples using API versioning, OpenAPI, and Scalar: