Swagger Integration

OtterApi ships with OtterApiSwaggerDocumentFilter, a Swashbuckle document filter that automatically adds all auto-generated routes to your Swagger / OpenAPI specification. One line of configuration is all that is needed.

Setup

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    options.DocumentFilter<OtterApiSwaggerDocumentFilter>();  // ← add this
});

What is auto-generated

The filter generates the full OpenAPI spec for every registered entity. This includes:

• Schemas for all registered entities
• Operations for GET (list, by id, count, pagedresult), POST, PUT, PATCH, and DELETE — respecting each entity's .Allow() configuration
• Custom named routes (WithCustomRoute) — with correct single-mode response schema (object vs. array) and 404 response when applicable
• Query parameter descriptions for all operations: filter[...], sort[...], page, pagesize, include, operator
• Type mappings for: string, bool, byte, sbyte, short, ushort, int, uint, long, ulong, float, double, decimal, DateTime, DateTimeOffset, Guid, byte[], enum
• Enum schemas include x-enumNames (for code generators such as NSwag / Kiota) and a human-readable description mapping integers to names (e.g. 0 = Pending, 1 = Active)
• The pagedresult response schema (when .ExposePagedResult() is used)

Complete example with Swagger UI

builder.Services.AddSwaggerGen(opt =>
{
    opt.SwaggerDoc("v1", new OpenApiInfo { Title = "Shop API", Version = "v1" });
    opt.DocumentFilter<OtterApiSwaggerDocumentFilter>();
});

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();
app.UseAuthentication();
app.UseAuthorization();
app.UseOtterApi();
app.MapControllers();
app.Run();