AutoRest should provide a way to mark types and properties as deprecated

[brjohnstmsft]

As APIs mature, occasionally we decide to remove features. It would be really handy if we could declare our intent to deprecate things in the API spec and have AutoRest flow it through to the generated code. For example, in C# it could add ObsoleteAttribute to generated properties or classes.

[fearthecowboy]

I have good news and less good news.

In swagger, there is a deprecated flag http://swagger.io/specification/#operationObject ... but we don't currently do anything with it.

To go along with it, I'd we might think about having a cmdline switch to 'don't generate deprecated APIs'.

This is will fit in nicely in post 1.0 -- opening up the model pipeline will let this work much better.

[brjohnstmsft]

@fearthecowboy This issue isn't fixed. Was it closed by mistake?

[fearthecowboy]

Weird... I never closed it... Did one of your comments in the PR address this?

[brjohnstmsft]

No, but I probably mentioned this issue in a commit comment.

[begoldsm]

@fearthecowboy I like the idea of doing something special with the deprecated flag, but I would caution against simply not generating the APIs, since we need to have deprecated APIs available for a while with the "deprecated warning" for the customer to know that this API will soon disappear. It would be bad if, by flagging something as deprecated, it just disappeared :)

[brjohnstmsft]

+What @begoldsm said. Let SDK authors decide when to remove stuff, not the tool. The point is to have the tool generate code that produces a warning.

[fearthecowboy]

Hence, my comment:

To go along with it, I'd we might think about having a cmdline switch to 'don't generate deprecated APIs'.

So that the user is in control. Deprecated would be marked by default, optionally not generated by explicit action

[begoldsm]

Ah yes, that makes sense so long as both are available then we are good! I wonder if there is a requirement for the interim step of turning compiler warnings into compiler errors for a deprecated -> officially obsolete -> removed style of timeline. I admit I am not clear on the requirements that we need to adhere to for deprecating and ultimately removing a specific API.

[brjohnstmsft]

@fearthecowboy Ah, that makes more sense now. I'm not sure why we'd need such an option though, as when we fully deprecate something we'd remove it from the next API version and corresponding Open API spec.

[annatisch]

@tbombach, @brjohnstmsft, @John-Hart,
Hi, I was just taking a look at this with regards to the Python generator - it seems that the "deprecated" property only applies to an operation, not (as suggested by the issue title) properties or types - is this correct?
Adding a warning to a deprecated operation in the Python generator should be straight forward, however adding a warning to models or specific properties would be a more complex affair.....

[phil000]

@tbombach, @brjohnstmsft, @John-Hart

I've been having a look at this code-gen in AutoRest.0.17.1-Nightly20161023.nupkg for the use of Obsolete in C# generated client.

There are 3 ways to invoke the operation through the generated client but only 1 of them gets the obsolete attribute and generates a compiler warning:

var response1 = client.Permissions.CreatePermission(request); OK, gets warning
var response2 = client.Permissions.CreatePermissionAsync(request).Result; NO WARNING
var response3 = client.Permissions.CreatePermissionWithHttpMessagesAsync(request).Result; NO WARNING

[brjohnstmsft]

@olydis Looks like you've taken over this issue. Do you have any thoughts on supporting something like Swagger's "deprecated" setting for properties and types in addition to operations?

[olydis]

Ah yes, I'd have no problem doing that for the C# generator, but there are currently more pressing TODOs we gotta work on :-|

[lmazuel]

Made the Python spec here: #2096

[fearthecowboy]

Adding the notion of supporting 'obsolete' and 'deprecated' to vNext generators.