Feature Considerations for v.Next generators

[fearthecowboy]

• handle suffixes like "operations"/"models" consistently across languages and in general (see Node.js doesn't name it's operation classes the same as other languages #1491)
• consistently handle LRO intial, progress and final responses, like progress reporting or error handling (see LRO should provide a way to get initial response from server. #1418, Expose ARM Async operation progress #960, Update LRO state machine across all languages #1128, LRO properties should be omitted in generated code unless needed #1441, No way to return response object from long-running POST #2295)
• consider model flattening combined with polymorphism and multiple hierarchies (see AutoRest.Azure does not support addition of flattened properties in the derived class. #1409)
• handle optional body parameters consistently (see .NET SDK does not properly honor optional streams as parameters #1629)
• handle markdown documentation (see AutoRest doesn't remove HTML tags from documentation #1640, Support GitHub flavored Markdown in description #1562)
• support timeouts and other things (see Include http request message inside of TaskCancelledExceptions #1462; maybe the layered HttpClient approach, see proposed Storage SDK architecture; see [C#] Can't set Timeout from generated I***Client interface #1651, [C#] Generated ServiceClient does not set HttpClient.Timeout #1445)
• pluggable support of other media types (and probably native support of stuff like text/plain; see Support text/plain media type if strings are sent over the wire #1527; also check out NDJSON stream with an AutoRest generated C# ServiceClient #2650)
• better error treatment. Make error types modelable and put server response (message, etc.) into thrown exception (see Error modeling generates code with poor output for the final user #2022, AutoRest - Can the Response have the actual exception details from API #2496, Feature Request: Allow Multiple Exception Type definitions in Swagger #1024, The error message is general, need to specify the server exception message #1111, Specify customize exception type even there is no body #855, Requirement to model errors as "default" makes it hard to document error cases #1523, Add an extension point to Deserialise exceptions #2341, Add treat default type as error #1654)
• decoupling HL and LL code gen (implicit return values Mapping status codes to return values #787; abstract base classes Support extension for discriminator definition property to allow making base class abstract.  #995; multi-verb madness and required/readOnly; auto-properties like fresh UUIDs; HL models with Equals/GetHashCode/... C#: please add options to generate GetHashCode(), Equals()/IEquatable and INotifyPropertyChanged #1251; use external models for HL autorest extensions x-ms-external #1752; unsigned types Autorest should support creating properties with 'ulong' #2422)
• less data duplication during (de-)serialization (see (C#) Generated code should avoid extra copies of request data #684)
• better enums (non-string, see Support for non-string enum #833; extensible enum class/string, see Improve the enum modelAsString extension option (for strongly typed languages) #733; multi-select enums, see [Feature request]x-ms-enum doesn't support combination of enum values.  #1867; single value enums w/o const, see x-ms-enum extension always hides enum with a single value #1449)
• object initializer list instead of fixed constructors (see CSharp: auto-generated constructors seem brittle #747, Azure.CSharp should generate a constructor which includes all required properties #977 🎉)
• fix accessibility of some service client constructor (see Generated ServiceClient constructor no longer accessible #907)
• modularity, pluggability (see Feature request: C# extensibility points at runtime #1021)
• revise streaming (see Streaming non file content using C# client generator #673, All Stream request body APIs should use Transfer-Encoding:chunked #903)
• make models round trippable (deser. + ser = equivalent information) by default, i.e. add an additional properties bag unless additionalProperties is explicitly disabled
• ensure that POSTs can have empty json ie, {} bodies instead of sending an empty HTTP body. (Updated travis to use go 1.8.3 #2330)
• support configurable output formatting (tabs, charset, linefeeds)
• forward documentation (operation groups Documentation for operation groups #289; enums Title and Description are ignored for Enum's #1786)
• deprecated/obsolete on everything (see AutoRest should provide a way to mark types and properties as deprecated #1285) 🎉 (C#)
• allow specifying existing types to substitute for generated ones. (.Net Types? #2472)
• better default: non-primitive (see Failure trying to generate C# classes from Json file  #1833 (comment)), actually don't just send it over the wire (see What is the expected behavior of default in the Swagger specification? #1607)
• do the right thing regarding validation (What is the expected behavior of default in the Swagger specification? #1607 (comment))
• HL/convenience concerns:
  • return specific value depending on status code (i.e. even if actual response is empty) - careful, this is not about the wire, so think about appropriate representation
  • trivial transformations like a returned property of oneOf: number/string/boolean to string (if it is decided that one would rather deal with string than having to deal with... object? some complex type that encapsulates the oneOf?)
• consider allowing same property name to occur multiple times across inheritance chain (perfectly valid Swagger, but one has to consider the implications on code generation -- in C#, one could override, but what if the subclasses type is more narrow than the base one? use new?)

[begoldsm]

@fearthecowboy nice! Part of the "standard operation class names" for node should include this issue: Azure/azure-sdk-for-node#2193

[fearthecowboy]

@begoldsm Yeah, naming is one of those things that's going to get handled a lot differently in vNext generators. The current modeler/generators is just this side of nightmarish when it comes to doing that right. I suspect we're going to have a long conversation about that.

[olydis]

@fearthecowboy can't edit your comment anymore!

New ask: writeOnly. There are very valid scenarios where you wanna only send something ("required" for sending!) but not receive it (KeyVault secrets for example). Currently, there's just no sane way to model that:

• making it required is a violation of the Swagger spec since then it's also expected on responses (which we apparently don't validate so far which is why KeyVault marked it as required)
• making it non-required gives bad UX since then the signature doesn't force you to send it

[fearthecowboy]

@olydis -- maybe we can make something work with https://github.com/Azure/autorest/blob/41c3ebf69e2903497ac32a430c27a972a03acb16/docs/extensions/readme.md#x-ms-mutability (it's purely cosmetic at the moment...)

[olydis]

@fearthecowboy right either that, or implement writeOnly since that's what OpenAPI 3.0 does (or at least implement x-ms-mutability in a way that's compatible with that), https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#fixed-fields-20

[asvishnyakov]

@fearthecowboy @olydis Is there any progress about #609 (Generated C# code should be decorated with GeneratedCodeAttribute attribute)? It's very useful: for example, it tells analyzers to exclude AutoRest-generated code from analyze process.

[fearthecowboy]

(closing, will prep issues for vNext soon)