Skip to content

Commit

Permalink
doc stuff (Azure#2740)
Browse files Browse the repository at this point in the history
* Update ChangeLog.md

* Update interpretations.md
  • Loading branch information
olydis authored Nov 29, 2017
1 parent 031f9c8 commit 88eb9b3
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 122 deletions.
127 changes: 13 additions & 114 deletions ChangeLog.md
Original file line number Diff line number Diff line change
@@ -1,114 +1,13 @@
##2016.05.11 Version 0.16.0
* Fixed ruby require module_definition if namespace is specified. See [#831](https://github.com/Azure/autorest/issues/831)
* Added an exit code for AutoRest.exe to indicate success or error
* Added support for Unix time formatted dates with the `'unix-time'` format (#909)
* Serializing/deserializing Unix time formatted dates in C# and NodeJS to DateTime (C#) and Date (NodeJS)
* Added support for Base64Url formatted values with the `'base64url'` format (#805)
* Serializing/deserializing Base64Url formatted values in C# and NodeJS to byte\[\] (C#) and Buffer (NodeJS)
* Fixed issue where the contents of the output file for SingleFileGeneration are appended instead of replaced (#667)
* Made generated parameter group documentation more accurate for `'x-ms-parameter-grouping'` extension (#634)
* UserAgent header in ServiceClient now includes more detailed information (#583)
* Added the ability to specify a name in generated code for query parameters, entity headers, etc. with the [`'x-ms-client-name'`](https://github.com/Azure/autorest/blob/master/Documentation/swagger-extensions.md#x-ms-client-name)
* Bug fixes in all code generators (#722, #742, #745, #746, #819, #820, #824, #825, #889, #896, #897, #900, #915, #923, #934, #944, #943)

##2016.03.04 Version 0.15.0
* Added Java code generator!
* Added support for constants whenever parameters or properties are marked as required and have only one enum value (#281, #488)
* Added ability to flatten client model properties with the extension [`'x-ms-client-flatten':true`](https://github.com/Azure/autorest/blob/master/Documentation/swagger-extensions.md#x-ms-client-flatten) (#720)
* Support for parameterized host names (#672)
* Added Java code generator!
* Added support for constants whenever parameters or properties are marked as required and have only one enum value (#281, #488)
* Added ability to flatten client model properties with the extension [`'x-ms-client-flatten':true`](https://github.com/Azure/autorest/blob/master/Documentation/swagger-extensions.md#x-ms-client-flatten) (#720)
* Support for parameterized host names (#672)
* Added Python generator
* Based on the Python requests library.
* Added Python Client Runtime with support for skip token iteration, Azure Long Running operation polling and AAD token retrieval.
* Support for all swagger extensions.
* Generates reStructuredText Sphinx-compatible docstrings.
* Significantly improved the Ruby code generator by
* Introduced package version and package name
* Moved request building to clientruntime
* Improved Error messaging for deserialization and http errors
* Exposed environment variable: `export AZURE_HTTP_LOGGING=full|partial` to provide http debug logging
* Moved skip_url_encoding and skip_query_param_encoding into generic code generator
* Fixed long running operations
* Added ability to generate a single client from [multiple swagger documents](https://github.com/Azure/autorest/blob/master/Documentation/defining-clients-swagger.md#composite-clients)
* Changed generated C# code to produce non-nullable primitives whenever they are required (#375, #492)
* Added support for DateTimeOffset in C# via -UseDateTimeOffset setting (#500)
* Added ability to not include tool version in copyright header (#598)
* Added Docker container (docker pull azuresdk/autorest)
* Added [samples](https://github.com/Azure/autorest/tree/master/Samples) to GitHub repo
* Added support for Uuid/Guid across all the languages (#784)
* Improved help generated by running exe
* Bug fixes in all code generators (#439, #520, #629, #652, #668, #714, #730, #738, #752, #778, #797)

* Significantly improved the Ruby code generator by
* Introduced package version and package name
* Moved request building to clientruntime
* Improved Error messaging for deserialization and http errors
* Exposed environment variable: `export AZURE_HTTP_LOGGING=full|partial` to provide http debug logging
* Moved skip_url_encoding and skip_query_param_encoding into generic code generator
* Fixed long running operations
* Added ability to generate a single client from [multiple swagger documents](https://github.com/Azure/autorest/blob/master/Documentation/defining-clients-swagger.md#composite-clients)
* Changed generated C# code to produce non-nullable primitives whenever they are required (#375, #492)
* Added support for DateTimeOffset in C# via -UseDateTimeOffset setting (#500)
* Added ability to not include tool version in copyright header (#598)
* Added Docker container (docker pull azuresdk/autorest)
* Added [samples](https://github.com/Azure/autorest/tree/master/Samples) to GitHub repo
* Added support for Uuid/Guid across all the languages (#784)
* Improved help generated by running exe
* Bug fixes in all code generators (#439, #520, #629, #652, #668, #714, #730, #738, #752, #778, #797)


##2016.01.25 Version 0.14.0
* Implemented FormData support including File upload and download in C# and NodeJS (#562)
* Added support for paths with query parameters via x-ms-paths extension (#569)
* Published [Microsoft.Rest.ClientRuntime 2.0.0](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime/2.0.0), [Microsoft.Rest.ClientRuntime.Azure 3.0.0](https://www.nuget.org/packages/Microsoft.Rest.ClientRuntime.Azure/3.0.0), [ms-rest 1.8.0] (https://www.npmjs.com/package/ms-rest), and [ms-rest-azure 1.8.0](https://www.npmjs.com/package/ms-rest-azure)
* Added [json schema](https://github.com/Azure/autorest/blob/master/schema/swagger-extensions.json) for all custom extensions
* Added ability to pass code generation settings via [x-ms-code-generation-settings extension](https://github.com/Azure/autorest/blob/master/Documentation/swagger-extensions.md#x-ms-code-generation-settings) in swagger (#621)
* Wrapped HTTP request and HTTP response in a new object in C# clients to avoid being disposed in Exceptions (#624) - note this is a breaking change compared to clients generated in 0.13.0 version of AutoRest
* Change NodeJS generated code(#590, #620)
* Improved OData support in Microsoft.Rest.Azure (#567)
* Added OperationName to x-ms-pageable (#571)
* Improved Error handling in C# and NodeJS (#572, #606, #608)
* Bug fixes in all code generators (#557, #561, #564, #565, #605)

##2015.12.14 Version 0.13.0
* Added support for flattening body parameters when the number of properties is small (controlled via -ft parameter)
* Implemented support for strongly typed response headers
* Updated Microsoft.Rest.Azure.Authentication to support CoreClr
* Updated autorest.exe with aliases (e.g. -i for input, -o for output, -g for code generation)
* Added custom exception support in C# generator
* Added custom polymorphic discriminator support (x-ms-discriminator-value)
* Added method parameter grouping via x-ms-parameter-grouping extension (#381)
* Added support for decimal type (#83)
* Changed generated C# code does not depend on JsonConvert (#372)
* Changed generated C# code to make variables not clash with parameters (#309)
* Changed service interface in C# to implement IDisposable (#278)
* Added TypeScript support to NodeJS generator
* Added support for default values in methods parameters and model properties for NodeJS
* Added support for validation of method parameters and model properties for NodeJS
* Improved Parameter documentation for methods in NodeJS
* Updated Azure NodeJS and C# code generator with odata support and Resource Flattening
* Bug fixes in all code generators (#415, #419, #426, #447, #463, #491, #493, #497)

##2015.10.23 Version 0.12.0
* Added Ruby language support
* Implemented validation in C#
* Added support for duration and decimal data types
* Added support for dotnet (CoreClr) to Microsoft.Rest.ClientRuntime and Microsoft.Rest.ClientRuntime.Azure
* Bug fixes and improvements to all code generators (#255, #282, #291, #293, #294, #336, #348, #349, #350, #352, #363, #373, #374, #375, #377, #390, #395, #398, #399, #402)

##2015.08.05 Version 0.11.0
* Added Azure C# and Azure NodeJS client runtimes and code generators
* Bug fixes for C# and NodeJS code generators (#272, #260, #229, #246, #245, #239, #237, #230, #229, #217, #209, #206, #195, #194)

##2015.07.10 Version 0.10.0
* Improved C# Client Runtime and Code Generator
* Changed serialization implementation to use Newtonsoft.Json.Net library
* Fixed bugs
* Added NodeJS Client Runtime and Code Generator

##2015.03.27 Version 0.9.7
* Initial release of the C# Client Runtime
* Initial release of the code generator with support for C#
## 2017.11.29 Version 2.0.4210
* Use Ruby generator 3.x.x (instead of 2.x.x) by default, supports multi API version generation. Use `[email protected]/autorest.ruby@^2.0.0` to use the old generator.
* Extensible enum support for C#
* Generate API version metadata for C#
* Reactivated oav model validator plugin
* Integrated VSCode LSP
* Improved command line help (showing automatically in some situations that imply that the user may need it; Python and C# generator specific help)
* Feature coverage tracking for most generators (see [http://azure.github.io/autorest/dashboard.html](http://azure.github.io/autorest/dashboard.html))
* Better output colorization
* Various bugfixes (see #2727, #2694, #2689, #2688, #2685, #2674, #2671, #2655, #2434, #1734), most notably
* Nested schema definitions (outside of `definitions` section) completely ignored the `required` field
* Better support for huge OpenAPI files (caused stack overflow)
* Constant body parameters where not treated as constants
20 changes: 12 additions & 8 deletions docs/interpretations.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,18 @@ The purpose of this document is to record those decisions.

## application/json

[The RFC](https://tools.ietf.org/html/rfc4627) seems to not require handling of primitive values or null values, it merely says that parsers have to parse "JSON text", which is either an object or array. Beyond that, parsers may apparently do as they please.
For AutoRest, we extend the (de)serialization responsibilities as follows:
- *any* [JSON value](https://www.json.org/) must be supported, behaving just like `JSON.stringify`/`JSON.parse` in JavaScript
- an empty request/response payload is an alternative valid way to serialize `null`
[RFC 4627](https://tools.ietf.org/html/rfc4627) and [RFC 7159](https://tools.ietf.org/html/rfc7159) allow parsers to actually parse more than just JSON values:

Reference implementation:
> "A JSON parser MAY accept non-JSON forms or extensions."
We encountered situations in which servers send empty bodies that are meant to be interpreted as `null`, so AutoRest generated clients must deserialize such bodies as `null`.

### Summary
- any [JSON value](https://www.json.org/) must be supported (behaving just like `JSON.stringify`/`JSON.parse` in JavaScript)
- an empty request/response payload must deserialize to `null`

### Reference Implementation
``` TypeScript
const serialize = (obj: any): string => JSON.stringify(obj); // alternative 1
const serialize = (obj: any): string => obj === null ? "" : JSON.stringify(obj); // alternative 2
const serialize = (obj: any): string => JSON.stringify(obj);
const deserialize = (str: string): any => str === "" ? null : JSON.parse(str);
```
```

0 comments on commit 88eb9b3

Please sign in to comment.