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
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
Chances are, Swagger UI will render your
Obsolete actions (endpoints) as ordinary API endpoints, not as “deprecated” as you would expect.
So, what’s wrong? I just followed the change history from the API versioning sample:
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
Here we can see that
operation.Deprecated is already
true! Let’s see what was happened before this.
apiDescription.IsDeprecated(), the result will be
false. Bingo. We should prevent it from executing if it’s already
=, 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.
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]