deprecated property on operations in swagger.json

[alberto-riggi]

No description provided.

[alberto-riggi]

Hi,
I saw there was already a similar issue opened regarding the usage of deprecated on actions, but I think my question is different.
I was expecting that marking a service version as deprecated would have caused to also add the deprecated property on each operation in the swagger.json description (the same behavior as using the obsolete attribute on an action).

I'm kind of new to versioning and swagger.
Is it intentional? Am I missing something?

Regards

[commonsensesoftware]

There is no direct relationship or dependencies between API versioning and Swagger. The provided API Explorer can tell you whether a specific action is deprecated for a particular API version or whether the entire API version is deprecated (e.g. for a given API version, all containing actions are deprecated).

If you want a specific operation in Swagger to be marked as deprecated, it would be your responsibly to indicate that in your Swagger generator of choice (ex: Swashbuckle, NSwag, etc). API Versioning provides you with the necessary information to determine whether said API is deprecated, but it's up to you to take advantage of that information. The API Explorer can be used for other scenarios besides Swagger generation. The exact method in which you tie the two together depends on which Swagger generator you are using.

I hope that helps clear things up.

[alberto-riggi]

Thanks for answering me so quickly, really appreciate it.
Still one doubt.
If I get it correctly, Api Explorer says "this api version is deprecated" without specifying anything at the operation level. Then it should be the generator to interpret this information and mark all the operations of that version as deprecated. (And swashbuckle isn't doing it).
Is it like that?

Regards

[commonsensesoftware]

Correct. This is because:

1. API Explorer doesn't know anything about Swagger
2. Swagger generators (like Swashbuckle) only know about information provided by the default API Explorer interfaces
   a. ApiVersion and IsDeprecated are not standard properties on ApiDescription

While it's totally convenient for the two to marry up, it doesn't really make sense for either side to take a hard dependency on the other. The most ideal situation would be for someone in the community (wink, wink) to create a new package that did this pairing.

Although I don't plan to support directly wiring up Swagger information, I have absolutely no problems providing samples as to how it can/should be done. There was no existing reason that couldn't have been done today, I just hadn't done it (and I'm not exactly a Swagger expert). You didn't indicate which platform you're using, but I've updated all of the Swagger examples to set the deprecated member of the Swagger operation.

In updating the samples, I realized it's more difficult to set things up than it should be. Specifically, although you can determine if an action is deprecated, it's not necessarily easy to understand how to get the necessary information. I've gone ahead and submitted a PR that will add an IsDeprecated extension method to make this simpler. I likely won't ship this until the next patch though. Once I ship a new package version, I'll update the examples. In the meantime, you can use code provided in the examples. The extension methods are ultimately going to do the exact same thing.

I hope that helps.

[alberto-riggi]

It makes completely sense.
Thank you for such level of details and thanks for the examples (I'm using aspnet core).

I'm not sure what the package you are mentioning should do beside wiring the deprecated property to the api one. I don't know too much about swagger. I'll investigate more.

Thank you

[commonsensesoftware]

Your 100% correct - there's isn't very much required to connect the two. The biggest barrier is the dependency coupling. Unless the intrinsic interfaces for the API Explorer provided by ASP.NET define a facility to mark an API description as deprecated, there isn't a way to tie the two packages and libraries together. The simplest solution is a new library and package that can do this.

I already manage 8 libraries and packages related to API versioning. I also run this project almost entirely by myself. I simply don't have the capacity to take on more. My solution has currently just been to show how the pieces connect in the examples. Perhaps one of the Swagger generator libraries, like Swashbuckle, would define some type of hook to test if an API description is deprecated using some type of callback function. This is how API versions were paired back in Web API. I not sure where it would be setup, maybe in the options? Something like: options.IsDeprecatedPredicate = apiDescription => apiDescrption.IsDeprecated() where the default is always options.IsDeprecatedPredicate = apiDescription => false;. Obviously, that would have to be taken up with the Swagger libraries, but that's how I would imagine that test from the API versioning side could be wired up to the Swagger side without a direct library dependency.

[alberto-riggi]

Yeah, that'd be a good option.

[commonsensesoftware]

Looks like you're on your way. Come back if you have more questions. Keep an eye out for the new extension method (shortcut) in the next patch. ;) Thanks!

[alberto-riggi]

yes, thank you, the default value linked to the api.deprecated did the trick.
Yep, I'll look for the extension.

Thank you!

[commonsensesoftware]

FYI, versions 3.1.0 (Web API) and 3.2.0 (Core) of the API Explorer have been published which now contain the IsDeprecated extension method. The examples have been updated to reflect this new functionality as well. Thanks.

[alberto-riggi]

That's great.
Thank you!