[Question]: Ensuring the Correct Order of Operation and Schema Filters in Swashbuckle.AspNetCore

[gokayokutucu]

What are you wanting to achieve?

I want to provide the correct execution order of OperationFilter and SchemaFilter in Swashbuckle.AspNetCore when generating Swagger documents. In particular, I want my OperationFilter to first work to cache certain header names, then I want my SchemaFilter to ignore those cached header names. Despite specifying the order in my configuration, SchemaFilter runs before OperationFilter.

What code or approach do you have so far?

Here is a minimalistic code snippet demonstrating the issue:

public class CacheHeaderNamesOperationFilter : IOperationFilter
{
    public static List<string> CachedHeaderNames = new();
    
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // Caching header names logic
        CachedHeaderNames.Add("ExampleHeaderName");
    }
}

public class IgnoreCachedHeaderNamesSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        // Logic to ignore cached header names
        foreach (var header in CacheHeaderNamesOperationFilter.CachedHeaderNames)
        {
            schema.Properties.Remove(header);
        }
    }
}

services.AddSwaggerGen(c =>
{
    c.OperationFilter<CacheHeaderNamesOperationFilter>(); // First, cache the header names
    c.SchemaFilter<IgnoreCachedHeaderNamesSchemaFilter>(); // Then, ignore the cached header names
});

Despite this order, IgnoreCachedHeaderNamesSchemaFilter runs before CacheHeaderNamesOperationFilter.

What is the expected outcome?

The expected outcome is that CacheHeaderNamesOperationFilter should run before IgnoreCachedHeaderNamesSchemaFilter, ensuring that the cached header names are available for the schema filter to process and ignore. This way, the Swagger documentation accurately reflects the intended API design.

Additional context

No response

[martincostello]

Schemas are created as part of the process of enumerating the operations found in the document, which is why different types of filters run in a certain order.

For your specific scenario, to get the behaviour your want you probably need to use a document filter and remove the schemas you wish to ignore from the almost-final document before it is serialized after your operation processors have run.

[gokayokutucu]

Thank you, your response. In particular, what steps should I follow to get the correct order and how can I use the document filter correctly?
Also, you said that the different filter types work in a certain order, what exactly is this order?

[martincostello]

• Schema filters run when a schema is created:

  Swashbuckle.AspNetCore/src/Swashbuckle.AspNetCore.SwaggerGen/SchemaGenerator/SchemaGenerator.cs

  Line 37 in 85fefe4

  public OpenApiSchema GenerateSchema(

• Schemas are created when processing operations by taking into account their parameters, response etc.
• Operation filters are applied just after an operation is created

  Swashbuckle.AspNetCore/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs

  Line 339 in 85fefe4

  await applyFilters(operation, filterContext);

• Document filters run last, just before the document is returned for serialization:

  Swashbuckle.AspNetCore/src/Swashbuckle.AspNetCore.SwaggerGen/SwaggerGenerator/SwaggerGenerator.cs

  Lines 60 to 68 in 85fefe4

  	foreach (var filter in _options.DocumentAsyncFilters)
  	{
  	await filter.ApplyAsync(swaggerDoc, filterContext, CancellationToken.None);
  	}
  	foreach (var filter in _options.DocumentFilters)
  	{
  	filter.Apply(swaggerDoc, filterContext);
  	}

[gokayokutucu]

Thank you very much for your response. It really helped me a lot.