OpenAPI and Scalar (Web API)

The rule

The OpenAPI document is generated at runtime by Microsoft.AspNetCore.OpenApi and served at /openapi/v1.json. Scalar (Scalar.AspNetCore) renders it at /scalar. Operation and schema text comes from XML comments on the actions and request classes (xml-docs-and-openapi), and each operation's tag comes from its controller name. Everything else is set by transformers in src/Presentation/OpenApi/.

Scalar is set up in ProgramExtensions.ConfigureApplication with the title, C# HttpClient as the default code sample, and its developer tools, agent, MCP and telemetry features turned off.

tests/Presentation.Tests.Integration/OpenApi/OpenApiDocumentTests.cs reads the generated document and fails if an operation has no summary, description, sample request or parameter descriptions, or a schema property has no description.

Steps

1. A new controller needs a CreateTag(...) line in DocumentInfoTransformer, named like the controller without Controller, with a one-sentence description.
2. Something every operation needs goes in an operation transformer; something about the whole API goes in a document transformer. Register it in AddOpenApi in ProgramExtensions.ConfigureBuilder.
3. Transformers are classes implementing IOpenApiDocumentTransformer or IOpenApiOperationTransformer, sealed, with XML docs. Unit test them in tests/Presentation.Tests.Unit/OpenApi/.
4. When you add an action, update the operation count in GetOpenApiDocument_ShouldDescribe_EveryOperation.
5. Run the app and read the result at http://localhost:7340/scalar.

Example

// src/Presentation/Extensions/ProgramExtensions.cs
_ = builder.Services.AddOpenApi(options =>
{
    _ = options.AddDocumentTransformer<DocumentInfoTransformer>();

    // Only with --include-auth.
    if (authentication.Enabled)
    {
        _ = options.AddDocumentTransformer<BearerSecurityTransformer>();
        _ = options.AddOperationTransformer<BearerSecurityTransformer>();
    }
});

// src/Presentation/Extensions/ProgramExtensions.cs
_ = app.MapOpenApi();
_ = app.MapScalarApiReference(options => options
    .WithTitle("CleanWebApi API")
    .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient)
    .HideDeveloperTools()
    .DisableAgent()
    .DisableMcp()
    .DisableTelemetry());

Don't

• Add Swashbuckle or NSwag. The built-in generator and Scalar replace them.
• Describe operations with [EndpointSummary] or [EndpointDescription]. The XML comments are the one source.
• Set [Tags] on an action. The controller name is the tag.
• Turn Scalar telemetry back on.
• Add the security scheme when authentication is off. The reference would ask for a token nobody needs.

Check

dotnet test --filter "FullyQualifiedName~OpenApi"
dotnet run --project ./src/Presentation   # then open http://localhost:7340/scalar