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?

This might help: https://stackoverflow.com/questions/37350241/swagger-cross-out-method — Rui Jarimba, Jul 09 '18 at 08:16
It doesn't.. The deprecated = true also doesn't appear in the swagger.json, so the deprecation flag isn't recognized at all — remcolam, Jul 09 '18 at 08:54

Helder Sepulveda · Accepted Answer · 2018-07-09T15:23:49.707

3

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.

edited Jul 09 '18 at 15:23

answered Jul 09 '18 at 15:05

Helder Sepulveda

15,500
4
29
56

4

OpenAPI 3.0 supports `deprecated` for models and properties. But Swashbuckle does not seem to support it yet. – Helen Jul 09 '18 at 15:18
Thanks for the clarification @Helen! Do you have any stats on the usage/adoption of 3.0? – Helder Sepulveda Jul 09 '18 at 15:22
I don't have stats, but here's a list of [known OAS3 implementations](https://github.com/OAI/OpenAPI-Specification/blob/master/IMPLEMENTATIONS.md). – Helen Jul 09 '18 at 16:10
I downvoted this answer as it mislead me that Obsolete attribute is not supported at all in Swagger. It is supported and Swagger behavior is to not display it in model definition and in example. But IgnoreObsoleteProperties flag must be set in Swagger Config which is false by default. – rybers Feb 10 '21 at 10:10

score 3 · Answer 2 · answered Jul 02 '21 at 01:46

3

[Obsolete]
public string Property {get; set;}

services.AddSwaggerGen(x => 
    // your other settings...
    x.IgnoreObsoleteProperties();
)

This works for me

answered Jul 02 '21 at 01:46

Robbie Cheng

31
1

1

This just completely ignores the properties, it doesn't mark them as obsolete? At least IgnoreObsoleteActions() completely removes endpoints from the swagger doc. – Heinzlmaen Jul 26 '22 at 06:22

score 2 · Answer 3 · answered Feb 10 '21 at 10:04

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:

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

3 Answers3