Add more info to README

README.md

@@ -1,4 +1,4 @@
-# schemars
+# Schemars
 
 [![Travis (.org)](https://img.shields.io/travis/GREsau/schemars?logo=travis)](https://travis-ci.org/GREsau/schemars)
 [![Crates.io](https://img.shields.io/crates/v/schemars)](https://crates.io/crates/schemars)
@@ -9,97 +9,175 @@ Work in progress!
 
 ## Basic Usage
 
+If you don't really care about the specifics, the easiest way to generate a JSON schema for you types is to `#[derive(JsonSchema)]` and use the `schema_for!` macro:
+
+```rust
+use schemars::{schema_for, JsonSchema};
+
+#[derive(JsonSchema)]
+pub struct MyStruct {
+    pub my_int: i32,
+    pub my_bool: bool,
+    pub my_nullable_enum: Option<MyEnum>,
+}
+
+#[derive(JsonSchema)]
+pub enum MyEnum {
+    Unit,
+    StringNewType(String)
+}
+
+fn main() {
+    let schema = schema_for!(MyStruct);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}
+```
+
+<details>
+<summary>Click to see the output JSON schema...</summary>
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "definitions": {
+    "MyEnum": {
+      "anyOf": [
+        {
+          "enum": [
+            "Unit"
+          ]
+        },
+        {
+          "type": "object",
+          "required": [
+            "StringNewType"
+          ],
+          "properties": {
+            "StringNewType": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    }
+  },
+  "type": "object",
+  "required": [
+    "my_bool",
+    "my_int",
+    "my_nullable_enum"
+  ],
+  "properties": {
+    "my_bool": {
+      "type": "boolean"
+    },
+    "my_int": {
+      "type": "integer",
+      "format": "int32"
+    },
+    "my_nullable_enum": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/MyEnum"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  }
+}
+```
+</details>
+
+### Serde Compatibility
+
+One of the main aims of this library is compatibility with [serde](https://github.com/serde-rs/serde). Any generated schema *should* match how [serde_json](https://github.com/serde-rs/json) would serialize/deserialize to/from JSON. To support this, Schemars will check for any `#[serde(...)]` attributes on types that derive `JsonSchema`, and adjust the generated schema accordingly.
+
 ```rust
 use schemars::{schema_for, JsonSchema};
 use serde::{Deserialize, Serialize};
 
 #[derive(Deserialize, Serialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
-struct MyStruct {
-    my_int: i32,
-    my_nullable: Option<bool>,
-    my_nested_struct: Nested,
+pub struct MyStruct {
+    #[serde(rename = "myNumber")]
+    pub my_int: i32,
+    pub my_bool: bool,
+    #[serde(default)]
+    pub my_nullable_enum: Option<MyEnum>,
 }
 
 #[derive(Deserialize, Serialize, JsonSchema)]
-#[serde(rename_all = "camelCase")]
-struct Nested {
-    #[serde(default)]
-    my_string: String,
-    #[serde(rename = "myArray")]
-    my_float_vec: Vec<f32>,
-    my_recursive_struct: Option<Box<Nested>>,
+#[serde(untagged)]
+pub enum MyEnum {
+    Unit,
+    StringNewType(String)
 }
 
-fn main() -> Result<(), Box<dyn std::error::Error>> {
+fn main() {
     let schema = schema_for!(MyStruct);
-    println!("{}", serde_json::to_string_pretty(&schema)?);
-    Ok(())
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
 }
+
 ```
 
-This outputs the following:
+<details>
+<summary>Click to see the output JSON schema...</summary>
 
 ```json
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "MyStruct",
-  "type": "object",
   "definitions": {
-    "Nested": {
-      "type": "object",
-      "required": [
-        "myArray",
-        "myRecursiveStruct"
-      ],
-      "properties": {
-        "myArray": {
-          "type": "array",
-          "items": {
-            "type": "number",
-            "format": "float"
-          }
+    "MyEnum": {
+      "anyOf": [
+        {
+          "type": "null"
         },
-        "myRecursiveStruct": {
-          "anyOf": [
-            {
-              "$ref": "#/definitions/Nested"
-            },
-            {
-              "type": "null"
-            }
-          ]
-        },
-        "myString": {
+        {
           "type": "string"
         }
-      }
+      ]
     }
   },
+  "type": "object",
   "required": [
-    "myInt",
-    "myNestedStruct",
-    "myNullable"
+    "myBool",
+    "myNumber"
   ],
   "properties": {
-    "myInt": {
+    "myBool": {
+      "type": "boolean"
+    },
+    "myNullableEnum": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/MyEnum"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "myNumber": {
       "type": "integer",
       "format": "int32"
-    },
-    "myNestedStruct": {
-      "$ref": "#/definitions/Nested"
-    },
-    "myNullable": {
-      "type": [
-        "boolean",
-        "null"
-      ]
     }
   }
 }
 ```
+</details>
 
-Note that the `#[serde(...)]` attributes are respected.
+`#[serde(...)]` attributes can be overriden using `#[schemars(...)]` attributes, which behave identically (e.g. `#[schemars(rename_all = "camelCase")]`). You may find this useful if you want to change the generated schema without affecting Serde, or if you're just not using Serde.
+
+## Feature Flags
+- `chrono` - implements `JsonSchema` for all [Chrono](https://github.com/chronotope/chrono) types which are serializable by Serde.
+- `derive_json_schema` - implements `JsonSchema` for Schemars types themselves
+
+## Customizing Schema Generation
+TODO document!
 
 ## TODO
 - Documentation