example: Add an example demonstrating how to do nested fields

Closes #490

Author: kevmoo

example/lib/nested_values_example.dart

@@ -0,0 +1,37 @@
+import 'package:json_annotation/json_annotation.dart';
+
+part 'nested_values_example.g.dart';
+
+/// An example work-around for
+/// https://github.com/google/json_serializable.dart/issues/490
+@JsonSerializable()
+class NestedValueExample {
+  NestedValueExample(this.nestedValues);
+
+  factory NestedValueExample.fromJson(Map<String, dynamic> json) =>
+      _$NestedValueExampleFromJson(json);
+
+  @_NestedListConverter()
+  @JsonKey(name: 'root_items')
+  final List<String> nestedValues;
+
+  Map<String, dynamic> toJson() => _$NestedValueExampleToJson(this);
+}
+
+class _NestedListConverter
+    extends JsonConverter<List<String>, Map<String, dynamic>> {
+  const _NestedListConverter();
+
+  @override
+  List<String> fromJson(Map<String, dynamic> json) => [
+        for (var e in json['items'] as List)
+          (e as Map<String, dynamic>)['name'] as String
+      ];
+
+  @override
+  Map<String, dynamic> toJson(List<String> object) => {
+        'items': [
+          for (var item in object) {'name': item}
+        ]
+      };
+}

example/lib/nested_values_example.g.dart

@@ -8,6 +8,9 @@ dependencies:
   json_annotation: ^4.4.0
 
 dev_dependencies:
+  # Used by tests. Not required to use `json_serializable`.
+  _json_serial_shared_test:
+    path: ../shared_test
   build_runner: ^2.0.0
 
   # Used by tests. Not required to use `json_serializable`.

example/pubspec.yaml

@@ -0,0 +1,35 @@
+// Copyright (c) 2020, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'dart:convert';
+
+import 'package:_json_serial_shared_test/shared_test.dart';
+import 'package:example/nested_values_example.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('NestedValueExample', () {
+    final input = jsonDecode(_input) as Map<String, dynamic>;
+    final normalizedOutput = loudEncode(input);
+
+    final instance = NestedValueExample.fromJson(input);
+
+    expect(loudEncode(instance), normalizedOutput);
+  });
+}
+
+const _input = r'''
+{
+  "root_items": {
+      "items": [
+          {
+              "name": "first nested item"
+          },
+          {
+              "name": "second nested item"
+          }
+      ]
+  }
+}
+''';