C# Swashbuckle: Obsolete model property shows without change in swagger

Question

I've marked a property as obsolete in my (input)model

public class MyModel
{
   [Obsolete("Use 'OtherProperty'")]
   public string SomeProperty {get;set;}


   public List<string> OtherProperty {get;set;}
}

However, swagger shows no distinction between the two properties, neither does it show the message.

Is there any way I can get swagger to honor the Obsolete attribute? Or will I need to put this in the xml-comments above the property myself?

Answer 1

Unfortunately there is no support for obsolete properties on Swashbuckle yet...

We are limited by the OpenAPI-Specification, and Swashbuckle still using 2.0
The closest thing is deprecated but that is available only for the methods not for properties:
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operation-object

• One option will be to hack something using an IDocumentFilter to completely hide those properties tagged with Obsolete but that will be a bumpy road.

• Another option is to create two methods and two models, that way you can tag the method and that will transition to the method within, everything will be deprecated (I think this is a bit messy) but I have seen this pattern used in many web-api

I think your best/easiest solution is what you suggested add some xml comments noting that the property should not be used.

Answer 2

It works for me by simply decorating property with [Obsolete] attribute (from System namespace) and setting the Swagger flag IgnoreObsoleteProperties to true. I added also property SomePropertySpecified, which is automatically set to true by serializer in case SomeProperty exists in request (null value does not mean that property did not exist). I have a custom logic to return appropriate error message if SomePropertySpecified is true.

public class Item
{
    [Obsolete]
    public string SomeProperty { get; set; }
    
    [JsonIgnore]
    public bool SomePropertySpecified { get; set; }

    public List<string> OtherProperty { get; set; }
}

Class SwaggerConfig:

public class SwaggerConfig
{
    public static void Register()
    {
        GlobalConfiguration.Configuration 
            .EnableSwagger(c =>
                {
                    c.SingleApiVersion("v1", "Demo");
                    c.IgnoreObsoleteProperties();
                })
            .EnableSwaggerUi(c =>
                {
                    c.DocExpansion(DocExpansion.Full);
                });
    }
}

Swagger UI: