openapi-and-scalar · git:20261103.92e9afa · 2026-11-03 · sha256 3b31c69af2353ccd
openapi-and-scalar git:20261103.92e9afaA
Immutable. This exact content never changes and is served at /api/v1/blob/3b31c69af2353ccd.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_zvn2sr3dukw2nlon/3b31c69af2353ccd15779d54573ba97dfc3edab1fac0f46c44c8f171a1af8341.json
Then /plugin install openapi-and-scalar@markdownregistry-zvn2sr3dukw2nlon in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: openapi-and-scalar
description: How this Web API builds its OpenAPI document and serves the Scalar API reference - AddOpenApi, the document and operation transformers, the bearer scheme when authentication is on, the Scalar options, and the tests that read the generated document. Use when changing the API description, tags, security scheme, Scalar settings, or when the API reference looks wrong.
metadata:
scope: presentation
---
# 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/`.
| Transformer | Adds |
| --- | --- |
| `DocumentInfoTransformer` | Title (with the environment name), description, contact, licence, external docs and the tag descriptions |
| `BearerSecurityTransformer` | Only when `Authentication:Authority` is set: the `Bearer` security scheme, a security requirement and a `401` response on every operation that needs a token |
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:8080/scalar>.
## Example
```csharp
// src/Presentation/Extensions/ProgramExtensions.cs
_ = builder.Services.AddOpenApi(options =>
{
_ = options.AddDocumentTransformer<DocumentInfoTransformer>();
if (authentication.Enabled)
{
_ = options.AddDocumentTransformer<BearerSecurityTransformer>();
_ = options.AddOperationTransformer<BearerSecurityTransformer>();
}
});
```
```csharp
// 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
``` bash
dotnet test --filter "FullyQualifiedName~OpenApi"
dotnet run --project ./src/Presentation # then open http://localhost:8080/scalar
```