Does the library work with Scalar documentation?

[marcuscfarias]

I was trying to find a way to add my fluent validation rules into scalar documentation and saw this issue #149. However, I wasn't able to configure.

Thus, I want to know if it works not only with swagger, but Scalar.

Thanks

[avgalex]

Yes, this library works with Scalar (and any other OpenAPI-compatible UI).

This library operates at the Swashbuckle schema generation level — it modifies the OpenAPI specification via ISchemaFilter and IOperationFilter before any UI renders it. The enriched OpenAPI JSON with all FluentValidation constraints (required, minLength, maxLength, pattern, etc.) is then consumed by whatever UI you choose — Swagger UI, Scalar, Redoc, etc.

Example setup with Scalar

dotnet add package Swashbuckle.AspNetCore
dotnet add package FluentValidation.DependencyInjectionExtensions
dotnet add package MicroElements.Swashbuckle.FluentValidation.AspNetCore
dotnet add package Scalar.AspNetCore

// Program.cs
using FluentValidation;
using MicroElements.Swashbuckle.FluentValidation.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Register FluentValidation validators
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

// Add FluentValidation rules to Swagger schema
builder.Services.AddFluentValidationRulesToSwagger();

var app = builder.Build();

// Serve Swashbuckle-generated OpenAPI JSON at the path Scalar expects
app.UseSwagger(c => c.RouteTemplate = "openapi/{documentName}.json");

// Scalar reads the enriched OpenAPI spec at /openapi/v1.json
app.MapScalarApiReference();

app.MapControllers();
app.Run();

Important: By default Scalar looks for the OpenAPI document at /openapi/{documentName}.json, while Swashbuckle serves it at /swagger/{documentName}/swagger.json. You need to align the route using either:

• app.UseSwagger(c => c.RouteTemplate = "openapi/{documentName}.json"); — change Swashbuckle's route, or
• Configure Scalar to point to Swashbuckle's default path

Scalar will display the validation constraints (required fields, min/max length, patterns, etc.) from the same OpenAPI JSON that Swagger UI uses.

Could you share more details about what exactly didn't work when you tried to configure it? That would help us provide more specific guidance.

[avgalex]

Update: Looking at #149 more closely, you might be using .NET's built-in OpenAPI (Microsoft.AspNetCore.OpenApi) rather than Swashbuckle. In that case, use the dedicated package MicroElements.AspNetCore.OpenApi.FluentValidation:

Setup with built-in OpenAPI + Scalar (recommended for .NET 9+)

dotnet add package FluentValidation.DependencyInjectionExtensions
dotnet add package MicroElements.AspNetCore.OpenApi.FluentValidation
dotnet add package Scalar.AspNetCore

using FluentValidation;
using MicroElements.AspNetCore.OpenApi.FluentValidation;

var builder = WebApplication.CreateBuilder(args);

// Register FluentValidation validators
builder.Services.AddValidatorsFromAssemblyContaining<Program>();

// Register FluentValidation rules for OpenAPI
builder.Services.AddFluentValidationRulesToOpenApi();

// Add OpenApi with FluentValidation transformer
builder.Services.AddOpenApi(options =>
{
    options.AddFluentValidationRules();
});

var app = builder.Build();

// Serve the OpenAPI document
app.MapOpenApi();

// Scalar reads the OpenAPI spec with FluentValidation rules applied
app.MapScalarApiReference();

app.Run();

Key points:

• Use MicroElements.AspNetCore.OpenApi.FluentValidation (NOT MicroElements.Swashbuckle.FluentValidation) when using .NET's built-in OpenAPI
• Both AddFluentValidationRulesToOpenApi() and options.AddFluentValidationRules() are required
• Supported in version 7.1.0+ (with full .NET 10 support)

You can also check the working sample: SampleAspNetCoreOpenApi

[marcuscfarias]

Actually, it worked! Thank you for building this library, very useful.

I would like to warn you for some unexpected behaviour that I noticed. Follow the thread:

1. I refactored my code to the solution you send me above.
2. My validator looks like this and the output is below, you can observate that is not showing anything for the description field:

namespace Ecommerce.Catalog.Api.Categories.CreateCategory;

internal sealed class CreateCategoryRequestValidator : AbstractValidator<CreateCategoryRequest>
{
    public CreateCategoryRequestValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MinimumLength(3)
            .MaximumLength(30);

        RuleFor(x => x.Slug)
            .NotEmpty()
            .MinimumLength(3)
            .MaximumLength(30)
            .Matches("^[a-z0-9]+(?:-[a-z0-9]+)*$")
            .WithMessage("'Slug' must contain only lowercase letters, digits, and hyphens.");

        RuleFor(x => x.Description)
            .MinimumLength(10)
            .MaximumLength(100)
            .When(x => x.Description is not null);
    }
}

3. However, when I comment the line .When(x => x.Description is not null);, the output works:

public CreateCategoryRequestValidator()
    {
        RuleFor(x => x.Name)
            .NotEmpty()
            .MinimumLength(3)
            .MaximumLength(30);

        RuleFor(x => x.Slug)
            .NotEmpty()
            .MinimumLength(3)
            .MaximumLength(30)
            .Matches("^[a-z0-9]+(?:-[a-z0-9]+)*$")
            .WithMessage("'Slug' must contain only lowercase letters, digits, and hyphens.");

        RuleFor(x => x.Description)
            .MinimumLength(10)
            .MaximumLength(100);
        // .When(x => x.Description is not null);
    }

4. I don't know if its right, but Claude Code gave me this explanation below:

5. Conclusion: it doesn't change any behaviour on the fluent validation pipeline, I already tested.

I hope it helps! In case you want to test, the source code is here: https://github.com/marcuscfarias/ecommerce-platform/tree/feat/category-create

[avgalex]

@marcuscfarias Glad it works for you! 🎉

Regarding the .When() behavior — this is expected and by design.

Why rules with .When() are skipped:

The library generates OpenAPI schemas at build/startup time, not at request time. A .When(x => x.Description is not null) condition depends on runtime data that doesn't exist during schema generation. Since the library cannot evaluate the condition, it skips the rule entirely to avoid generating potentially incorrect schema constraints.

If you want to include conditional rules in the schema, you can override the default RuleFilter when configuring the library:

services.AddFluentValidationRulesToSwagger(options =>
{
    // Include rules even if they have conditions
    options.SetNotFluentValidationFilterForType<MyType>();
    
    // Or globally include all conditional rules:
    // options.RuleFilter = new Condition<ValidationRuleContext>(_ => true);
});

⚠️ Note: Enabling conditional rules globally means the schema may show constraints that only apply under certain conditions, which could be misleading for API consumers.

Your specific case — .When(x => x.Description is not null) is essentially a null-guard. Since Description is already nullable, the MinimumLength/MaximumLength validators won't fire on null values anyway (FluentValidation skips null by default for these validators). So removing the .When() clause is the correct fix here — the behavior is identical.

Thanks for the detailed report and the repo link!

[avgalex]

Follow-up: I want to be transparent — the behavior with .When() is a known limitation, not just a design choice.

The core problem: when you write .When(x => x.Description is not null), the library sees that the rule has a condition but cannot analyze the lambda to determine whether it's a null-guard (safe to include in schema) or a business condition like .When(x => x.Role == "admin") (misleading if included).

Since we can't distinguish between the two, the current default is conservative — skip all conditional rules. This is safe but loses valid schema constraints in cases like yours.

We're considering ways to improve this. In the meantime, the practical advice remains: for null-guards on nullable properties, simply remove .When() — FluentValidation validators like MinimumLength/MaximumLength already skip null values by default, so the behavior is identical.

[avgalex]

v7.1.5-beta released

We've published a beta package with a new ConditionalRulesMode option that addresses the .When() behavior discussed above.

What was done

New enum ConditionalRulesMode with three modes:

Mode	Behavior
Exclude (default)	Conditional rules are excluded from schema — existing behavior, backward-compatible
Include	Conditional rules are included in the schema
IncludeWithWarning	Same as Include, but logs a warning for each conditional rule included

Usage:

services.AddFluentValidationRulesToSwagger(options =>
{
    options.ConditionalRules = ConditionalRulesMode.Include;
});

With ConditionalRulesMode.Include, your original validator:

RuleFor(x => x.Description)
    .MinimumLength(10)
    .MaximumLength(100)
    .When(x => x.Description is not null);

will correctly produce minLength: 10 and maxLength: 100 in the OpenAPI schema.

Implementation details

• The option works at both rule-level (.When() at end of chain) and component-level (.When() on individual validator)
• IncludeWithWarning logging is built into the filter condition itself — it respects custom RuleFilter/RuleComponentFilter overrides (no spurious warnings if you set your own filter)
• 7 new tests covering all modes, component-level conditions, and custom filter override
• All tests pass on net8.0, net9.0, and net10.0

Links

• Branch: release/v7.1.5-beta
• Release: v7.1.5-beta

Please try the beta and let us know if it works for your use case!

[IeuanWalker]

@avgalex one option you could look into is too allow people to manually add/ alter or remove rules.
Its one of the features I built into my implementation of this feature - https://github.com/IeuanWalker/MinimalApi.Endpoints/wiki/WithValidationRules

That way if someone doesnt like something that was generated/ or something was missing, they could always add/ change it manually

[avgalex]

Thanks for the suggestion @IeuanWalker! That's an interesting approach in your MinimalApi.Endpoints framework.

In our case, manual rule override is already achievable through existing extension points:

1. RuleFilter / RuleComponentFilter — control which FluentValidation rules are included in the schema:

services.AddFluentValidationRulesToSwagger(options =>
{
    options.RuleFilter = new Condition<ValidationRuleContext>(context =>
    {
        // custom include/exclude logic per rule
        return true;
    });
});

2. Swashbuckle's built-in ISchemaFilter — for manually adding, modifying, or removing any schema properties after generation:

services.AddSwaggerGen(options =>
{
    options.SchemaFilter<MyCustomSchemaFilter>();
});

3. IFluentValidationRuleProvider — for adding custom mappings from FluentValidation validators to OpenAPI schema properties.

We prefer to keep our API surface minimal and rely on standard Swashbuckle extension points for manual overrides rather than introducing a parallel fluent API. This way users work with familiar Swashbuckle patterns.

The new ConditionalRulesMode option in v7.1.5-beta should solve the original problem of .When() guards silently dropping schema constraints. If you still need manual control beyond that, the extension points above should cover it.