[Swashbuckle and API Versioning] Obsolete attribute is not rendered as deprecated in Swagger UI

This post originally appeared on Medium

---

Upgraded ASP.NET Core 2.1 to 2.2: [Swashbuckle and API Versioning] Obsolete attribute is not rendered as deprecated in Swagger UI

Experiencing Obsolete action is not rendered as deprecated in Swagger UI?

So you’ve upgraded your ASP.NET Core 2.1 app to 2.2 and you are using:

• Swashbuckle.AspNetCore version 3.x
• API versioning (Microsoft.AspNetCore.Mvc.Versioning) version 3.x

AND, you have one or more of your API controller actions decorated as Obsolete?

Chances are, Swagger UI will render your Obsolete actions (endpoints) as ordinary API endpoints, not as “deprecated” as you would expect.

“Delete” action method marked as Obsolete

DELETE /api/v3/People/{id} should be rendered as “deprecated”…

So, what’s wrong? I just followed the change history from the API versioning sample:

Microsoft/aspnet-api-versioning

We can even see the git change history with a cool animation like this:

Use this link to see it yourself.

Still here? Okay, so here we have this line:

operation.Deprecated = apiDescription.IsDeprecated();

It should do the work to deprecate the endpoints. But there is one flaw. It is overwriting the previous value assigned somewhere by SwaggerGenerator.

Deprecated is true before the evaluation of “apiDescription.IsDeprecated()”

Here we can see that operation.Deprecated is already true! Let’s see what was happened before this.

https://github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/192aa2d70f057fc2805f58d51b6e859f1f6b07ce/src/Swashbuckle.AspNetCore.SwaggerGen/Generator/SwaggerGenerator.cs

After executing apiDescription.IsDeprecated(), the result will be false. Bingo. We should prevent it from executing if it’s already true.

Instead of =, we could short-circuit it by using |= so that once it has been marked as true — deprecated, we won’t even bother to look at it.

Now, the Swagger UI should render as expected.

DELETE /api/v3/People/{id} is rendered as “deprecated”

Problem solved!

I have spent a few hours digging into this wondering what the culprit was, since it was working before the upgrade. Is the sample code provided by the API versioning wrong? Not really. It’s merely a sample. Please understand that the sample won’t cover all of the possible cases. So we can’t blame it. But hey, I think the sample could be better. I know that this might be an edge case, but I will try to report it to the repo owner and maybe send a Pull Request to fix the sample code in the hope that it will save hours of debugging time of future users!

[ Update : I opened the issue here: https://github.com/microsoft/aspnet-api-versioning/issues/470]