Excluding Properties in Swashbuckle Swagger Documentation with Custom Schema Filters

Introduction

When using Swashbuckle to generate Swagger documentation for ASP.NET Web API projects, there might be scenarios where certain model properties need to be excluded from the documentation without affecting JSON serialization for other parts of the application. This is often the case when models are shared with legacy interfaces that require full serialization. Using attributes like JsonIgnore might not be suitable as it globally ignores the property in all JSON serialization contexts. This article presents a solution using custom schema filters in Swashbuckle to selectively ignore properties.

Implementing a Custom SwaggerExcludeAttribute

To mark properties that should be ignored in Swagger documentation, we can define a custom attribute. Here is an example in C#:

[AttributeUsage(AttributeTargets.Property)]
public class SwaggerExcludeAttribute : Attribute
{
}

This attribute can be applied to any property that you wish to hide from Swagger.

Creating an ISchemaFilter

Swashbuckle provides the ISchemaFilter interface to customize the schema generation. We can implement a filter that removes properties marked with the SwaggerExcludeAttribute.

public class SwaggerExcludeFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (schema.Properties == null || context.Type == null)
            return;
        var excludedProperties = context.Type.GetProperties()
                                         .Where(p => p.GetCustomAttribute<SwaggerExcludeAttribute>() != null);
        foreach (var prop in excludedProperties)
        {
            var propertyName = prop.Name;
            if (schema.Properties.ContainsKey(propertyName))
                schema.Properties.Remove(propertyName);
        }
    }
}

This filter uses reflection to find properties with the custom attribute and removes them from the Swagger schema.

Registering the Filter

To use the filter, it must be registered in the Swagger configuration. In the startup code, typically in ConfigureServices, add the following:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    c.SchemaFilter<SwaggerExcludeFilter>();
});

This ensures that the filter is applied when generating the Swagger documentation.

Alternative Approaches

While the above solution is effective, other methods exist. For instance, in .NET Core 3.1 or later, System.Text.Json.Serialization.JsonIgnore can be used, but it globally ignores the property in JSON serialization, which may not be desirable. Similarly, marking properties as internal or private can cause them to be ignored by Swashbuckle, but this affects data population in requests and responses, making it less flexible. Extended solutions, such as supporting fields and handling property name overrides with attributes like JsonProperty, can be implemented by enhancing the filter, as seen in other community answers.

Conclusion

Using custom schema filters in Swashbuckle allows developers to selectively exclude model properties from Swagger documentation without interfering with other serialization needs. By defining a simple attribute and implementing an ISchemaFilter, this approach provides a clean and maintainable solution. This method is particularly useful in scenarios where models are shared across different parts of an application, ensuring that Swagger documentation remains accurate and relevant.