OpenAPI Extensions

Scalar provides extension methods and attributes to enhance your OpenAPI documents with additional metadata that improves the API Reference experience.

Prerequisites

You must install and configure one of the companion packages to enable extensions:

For Microsoft.AspNetCore.OpenApi:

dotnet add package Scalar.AspNetCore.Microsoft

For Swashbuckle.AspNetCore.SwaggerGen:

dotnet add package Scalar.AspNetCore.Swashbuckle

Add the appropriate transformers/filters during OpenAPI registration:

using Scalar.AspNetCore;

// Microsoft.AspNetCore.OpenApi
```shell
dotnet add package Scalar.AspNetCore.Swashbuckle

Add the appropriate transformers/filters during OpenAPI registration:

using Scalar.AspNetCore;

// Microsoft.AspNetCore.OpenApi
builder.Services.AddOpenApi(options => options.AddScalarTransformers());

// Swashbuckle.AspNetCore.SwaggerGen
builder.Services.AddSwaggerGen(options => options.AddScalarFilters());

Extensions Overview

API Stability

Mark endpoints with their stability status to help developers understand production readiness:

// Minimal APIs
app.MapGet("/products", GetProducts).Stable();
app.MapGet("/beta-features", GetBetaFeatures).Experimental(); 
app.MapGet("/legacy-endpoint", GetLegacyData).Deprecated();

// Controllers
[HttpGet]
[Stability(Stability.Stable)]
public IActionResult GetProducts() => Ok();

Stability Levels:

  • Stable: Production-ready API
  • Experimental: API likely to change, not recommended for production
  • Deprecated: API will be removed in a future release

Exclude From API Reference

Hide internal endpoints from the API Reference while keeping them in the OpenAPI document:

// Minimal APIs
app.MapGet("/internal/metrics", GetMetrics).ExcludeFromApiReference();

// Controllers
[HttpGet]
[ExcludeFromApiReference]
public IActionResult GetInternalMetrics() => Ok();

Endpoints remain accessible via the API but won't appear in the Scalar API Reference interface.

Code Samples

Add custom code examples to help developers understand how to use your endpoints:

// Minimal APIs
app.MapPost("/orders", CreateOrder)
    .CodeSample("fetch('/orders', { method: 'POST', body: JSON.stringify(order) })", 
                ScalarTarget.JavaScript, "Create Order")
    .CodeSample("curl -X POST /orders -d @order.json", 
                ScalarTarget.Shell, "Create with cURL");

// Controllers  
[HttpGet]
[CodeSample("fetch('/products').then(r => r.json())", ScalarTarget.JavaScript)]
public IActionResult GetProducts() => Ok();