Add separate docs for v0.8/v1

docs/_includes/examples_v0/custom_serialization.rs

@@ -0,0 +1,60 @@
+use schemars::schema::{Schema, SchemaObject};
+use schemars::{gen::SchemaGenerator, schema_for, JsonSchema};
+use serde::{Deserialize, Serialize};
+
+// `int_as_string` and `bool_as_string` use the schema for `String`.
+#[derive(Default, Deserialize, Serialize, JsonSchema)]
+pub struct MyStruct {
+    #[serde(default = "eight", with = "as_string")]
+    #[schemars(with = "String")]
+    pub int_as_string: i32,
+
+    #[serde(default = "eight")]
+    pub int_normal: i32,
+
+    #[serde(default, with = "as_string")]
+    #[schemars(schema_with = "make_custom_schema")]
+    pub bool_as_string: bool,
+
+    #[serde(default)]
+    pub bool_normal: bool,
+}
+
+fn make_custom_schema(gen: &mut SchemaGenerator) -> Schema {
+    let mut schema: SchemaObject = <String>::json_schema(gen).into();
+    schema.format = Some("boolean".to_owned());
+    schema.into()
+}
+
+fn eight() -> i32 {
+    8
+}
+
+// This module serializes values as strings
+mod as_string {
+    use serde::{de::Error, Deserialize, Deserializer, Serializer};
+
+    pub fn serialize<T, S>(value: &T, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        T: std::fmt::Display,
+        S: Serializer,
+    {
+        serializer.collect_str(value)
+    }
+
+    pub fn deserialize<'de, T, D>(deserializer: D) -> Result<T, D::Error>
+    where
+        T: std::str::FromStr,
+        D: Deserializer<'de>,
+    {
+        let string = String::deserialize(deserializer)?;
+        string
+            .parse()
+            .map_err(|_| D::Error::custom("Input was not valid"))
+    }
+}
+
+fn main() {
+    let schema = schema_for!(MyStruct);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/custom_serialization.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "type": "object",
+  "properties": {
+    "bool_as_string": {
+      "default": "false",
+      "type": "string",
+      "format": "boolean"
+    },
+    "bool_normal": {
+      "default": false,
+      "type": "boolean"
+    },
+    "int_as_string": {
+      "default": "8",
+      "type": "string"
+    },
+    "int_normal": {
+      "default": 8,
+      "type": "integer",
+      "format": "int32"
+    }
+  }
+}

docs/_includes/examples_v0/custom_settings.rs

@@ -0,0 +1,24 @@
+use schemars::{gen::SchemaSettings, 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 {
+    StringNewType(String),
+    StructVariant { floats: Vec<f32> },
+}
+
+fn main() {
+    let settings = SchemaSettings::draft07().with(|s| {
+        s.option_nullable = true;
+        s.option_add_null_type = false;
+    });
+    let gen = settings.into_generator();
+    let schema = gen.into_root_schema_for::<MyStruct>();
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/custom_settings.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "type": "object",
+  "required": [
+    "my_bool",
+    "my_int"
+  ],
+  "properties": {
+    "my_bool": {
+      "type": "boolean"
+    },
+    "my_int": {
+      "type": "integer",
+      "format": "int32"
+    },
+    "my_nullable_enum": {
+      "allOf": [
+        {
+          "$ref": "#/definitions/MyEnum"
+        }
+      ],
+      "nullable": true
+    }
+  },
+  "definitions": {
+    "MyEnum": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "StringNewType"
+          ],
+          "properties": {
+            "StringNewType": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "StructVariant"
+          ],
+          "properties": {
+            "StructVariant": {
+              "type": "object",
+              "required": [
+                "floats"
+              ],
+              "properties": {
+                "floats": {
+                  "type": "array",
+                  "items": {
+                    "type": "number",
+                    "format": "float"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

docs/_includes/examples_v0/doc_comments.rs

@@ -0,0 +1,33 @@
+use schemars::{schema_for, JsonSchema};
+
+/// # My Amazing Struct
+/// This struct shows off generating a schema with
+/// a custom title and description.
+#[derive(JsonSchema)]
+pub struct MyStruct {
+    /// # My Amazing Integer
+    pub my_int: i32,
+    /// This bool has a description, but no title.
+    pub my_bool: bool,
+    /// # A Nullable Enum
+    /// This enum might be set, or it might not.
+    pub my_nullable_enum: Option<MyEnum>,
+}
+
+/// # My Amazing Enum
+#[derive(JsonSchema)]
+pub enum MyEnum {
+    /// A wrapper around a `String`
+    StringNewType(String),
+    /// A struct-like enum variant which contains
+    /// some floats
+    StructVariant {
+        /// The floats themselves
+        floats: Vec<f32>,
+    },
+}
+
+fn main() {
+    let schema = schema_for!(MyStruct);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/doc_comments.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "My Amazing Struct",
+  "description": "This struct shows off generating a schema with a custom title and description.",
+  "type": "object",
+  "required": [
+    "my_bool",
+    "my_int"
+  ],
+  "properties": {
+    "my_bool": {
+      "description": "This bool has a description, but no title.",
+      "type": "boolean"
+    },
+    "my_int": {
+      "title": "My Amazing Integer",
+      "type": "integer",
+      "format": "int32"
+    },
+    "my_nullable_enum": {
+      "title": "A Nullable Enum",
+      "description": "This enum might be set, or it might not.",
+      "anyOf": [
+        {
+          "$ref": "#/definitions/MyEnum"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "MyEnum": {
+      "title": "My Amazing Enum",
+      "oneOf": [
+        {
+          "description": "A wrapper around a `String`",
+          "type": "object",
+          "required": [
+            "StringNewType"
+          ],
+          "properties": {
+            "StringNewType": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "description": "A struct-like enum variant which contains some floats",
+          "type": "object",
+          "required": [
+            "StructVariant"
+          ],
+          "properties": {
+            "StructVariant": {
+              "type": "object",
+              "required": [
+                "floats"
+              ],
+              "properties": {
+                "floats": {
+                  "description": "The floats themselves",
+                  "type": "array",
+                  "items": {
+                    "type": "number",
+                    "format": "float"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

docs/_includes/examples_v0/enum_repr.rs

@@ -0,0 +1,15 @@
+use schemars::{schema_for, JsonSchema_repr};
+
+#[derive(JsonSchema_repr)]
+#[repr(u8)]
+enum SmallPrime {
+    Two = 2,
+    Three = 3,
+    Five = 5,
+    Seven = 7,
+}
+
+fn main() {
+    let schema = schema_for!(SmallPrime);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/enum_repr.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SmallPrime",
+  "type": "integer",
+  "enum": [
+    2,
+    3,
+    5,
+    7
+  ]
+}

docs/_includes/examples_v0/from_value.rs

@@ -0,0 +1,24 @@
+use schemars::schema_for_value;
+use serde::Serialize;
+
+#[derive(Serialize)]
+pub struct MyStruct {
+    pub my_int: i32,
+    pub my_bool: bool,
+    pub my_nullable_enum: Option<MyEnum>,
+}
+
+#[derive(Serialize)]
+pub enum MyEnum {
+    StringNewType(String),
+    StructVariant { floats: Vec<f32> },
+}
+
+fn main() {
+    let schema = schema_for_value!(MyStruct {
+        my_int: 123,
+        my_bool: true,
+        my_nullable_enum: Some(MyEnum::StringNewType("foo".to_string()))
+    });
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/from_value.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "examples": [
+    {
+      "my_bool": true,
+      "my_int": 123,
+      "my_nullable_enum": {
+        "StringNewType": "foo"
+      }
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "my_bool": {
+      "type": "boolean"
+    },
+    "my_int": {
+      "type": "integer"
+    },
+    "my_nullable_enum": true
+  }
+}

docs/_includes/examples_v0/main.rs

@@ -0,0 +1,19 @@
+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 {
+    StringNewType(String),
+    StructVariant { floats: Vec<f32> },
+}
+
+fn main() {
+    let schema = schema_for!(MyStruct);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/main.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "type": "object",
+  "required": [
+    "my_bool",
+    "my_int"
+  ],
+  "properties": {
+    "my_bool": {
+      "type": "boolean"
+    },
+    "my_int": {
+      "type": "integer",
+      "format": "int32"
+    },
+    "my_nullable_enum": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/MyEnum"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "definitions": {
+    "MyEnum": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "StringNewType"
+          ],
+          "properties": {
+            "StringNewType": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "StructVariant"
+          ],
+          "properties": {
+            "StructVariant": {
+              "type": "object",
+              "required": [
+                "floats"
+              ],
+              "properties": {
+                "floats": {
+                  "type": "array",
+                  "items": {
+                    "type": "number",
+                    "format": "float"
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

docs/_includes/examples_v0/remote_derive.rs

@@ -0,0 +1,42 @@
+// Pretend that this is somebody else's crate, not a module.
+mod other_crate {
+    // Neither Schemars nor the other crate provides a JsonSchema impl
+    // for this struct.
+    pub struct Duration {
+        pub secs: i64,
+        pub nanos: i32,
+    }
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+use other_crate::Duration;
+use schemars::{schema_for, JsonSchema};
+
+// This is just a copy of the remote data structure that Schemars can use to
+// create a suitable JsonSchema impl.
+#[derive(JsonSchema)]
+#[serde(remote = "Duration")]
+pub struct DurationDef {
+    pub secs: i64,
+    pub nanos: i32,
+}
+
+// Now the remote type can be used almost like it had its own JsonSchema impl
+// all along. The `with` attribute gives the path to the definition for the
+// remote type. Note that the real type of the field is the remote type, not
+// the definition type.
+#[derive(JsonSchema)]
+pub struct Process {
+    pub command_line: String,
+    #[serde(with = "DurationDef")]
+    pub wall_time: Duration,
+    // Generic types must be explicitly specified with turbofix `::<>` syntax.
+    #[serde(with = "Vec::<DurationDef>")]
+    pub durations: Vec<Duration>,
+}
+
+fn main() {
+    let schema = schema_for!(Process);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/remote_derive.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Process",
+  "type": "object",
+  "required": [
+    "command_line",
+    "durations",
+    "wall_time"
+  ],
+  "properties": {
+    "command_line": {
+      "type": "string"
+    },
+    "durations": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Duration"
+      }
+    },
+    "wall_time": {
+      "$ref": "#/definitions/Duration"
+    }
+  },
+  "definitions": {
+    "Duration": {
+      "type": "object",
+      "required": [
+        "nanos",
+        "secs"
+      ],
+      "properties": {
+        "nanos": {
+          "type": "integer",
+          "format": "int32"
+        },
+        "secs": {
+          "type": "integer",
+          "format": "int64"
+        }
+      }
+    }
+  }
+}

docs/_includes/examples_v0/schemars_attrs.rs

@@ -0,0 +1,30 @@
+use schemars::{schema_for, JsonSchema};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, JsonSchema)]
+#[schemars(rename_all = "camelCase", deny_unknown_fields)]
+pub struct MyStruct {
+    #[serde(rename = "thisIsOverridden")]
+    #[schemars(rename = "myNumber", range(min = 1, max = 10))]
+    pub my_int: i32,
+    pub my_bool: bool,
+    #[schemars(default)]
+    pub my_nullable_enum: Option<MyEnum>,
+    #[schemars(inner(regex(pattern = "^x$")))]
+    pub my_vec_str: Vec<String>,
+}
+
+#[derive(Deserialize, Serialize, JsonSchema)]
+#[schemars(untagged)]
+pub enum MyEnum {
+    StringNewType(#[schemars(phone)] String),
+    StructVariant {
+        #[schemars(length(min = 1, max = 100))]
+        floats: Vec<f32>,
+    },
+}
+
+fn main() {
+    let schema = schema_for!(MyStruct);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/schemars_attrs.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "type": "object",
+  "required": [
+    "myBool",
+    "myNumber",
+    "myVecStr"
+  ],
+  "properties": {
+    "myBool": {
+      "type": "boolean"
+    },
+    "myNullableEnum": {
+      "default": null,
+      "anyOf": [
+        {
+          "$ref": "#/definitions/MyEnum"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "myNumber": {
+      "type": "integer",
+      "format": "int32",
+      "maximum": 10.0,
+      "minimum": 1.0
+    },
+    "myVecStr": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^x$"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "MyEnum": {
+      "anyOf": [
+        {
+          "type": "string",
+          "format": "phone"
+        },
+        {
+          "type": "object",
+          "required": [
+            "floats"
+          ],
+          "properties": {
+            "floats": {
+              "type": "array",
+              "items": {
+                "type": "number",
+                "format": "float"
+              },
+              "maxItems": 100,
+              "minItems": 1
+            }
+          }
+        }
+      ]
+    }
+  }
+}

docs/_includes/examples_v0/serde_attrs.rs

@@ -0,0 +1,24 @@
+use schemars::{schema_for, JsonSchema};
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+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(untagged)]
+pub enum MyEnum {
+    StringNewType(String),
+    StructVariant { floats: Vec<f32> },
+}
+
+fn main() {
+    let schema = schema_for!(MyStruct);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/serde_attrs.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "type": "object",
+  "required": [
+    "myBool",
+    "myNumber"
+  ],
+  "properties": {
+    "myBool": {
+      "type": "boolean"
+    },
+    "myNullableEnum": {
+      "default": null,
+      "anyOf": [
+        {
+          "$ref": "#/definitions/MyEnum"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "myNumber": {
+      "type": "integer",
+      "format": "int32"
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "MyEnum": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "required": [
+            "floats"
+          ],
+          "properties": {
+            "floats": {
+              "type": "array",
+              "items": {
+                "type": "number",
+                "format": "float"
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

docs/_includes/examples_v0/validate.rs

@@ -0,0 +1,24 @@
+use schemars::{schema_for, JsonSchema};
+
+#[derive(JsonSchema)]
+pub struct MyStruct {
+    #[validate(range(min = 1, max = 10))]
+    pub my_int: i32,
+    pub my_bool: bool,
+    #[validate(required)]
+    pub my_nullable_enum: Option<MyEnum>,
+}
+
+#[derive(JsonSchema)]
+pub enum MyEnum {
+    StringNewType(#[validate(phone)] String),
+    StructVariant {
+        #[validate(length(min = 1, max = 100))]
+        floats: Vec<f32>,
+    },
+}
+
+fn main() {
+    let schema = schema_for!(MyStruct);
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples_v0/validate.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "MyStruct",
+  "type": "object",
+  "required": [
+    "my_bool",
+    "my_int",
+    "my_nullable_enum"
+  ],
+  "properties": {
+    "my_bool": {
+      "type": "boolean"
+    },
+    "my_int": {
+      "type": "integer",
+      "format": "int32",
+      "maximum": 10.0,
+      "minimum": 1.0
+    },
+    "my_nullable_enum": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "StringNewType"
+          ],
+          "properties": {
+            "StringNewType": {
+              "type": "string",
+              "format": "phone"
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": [
+            "StructVariant"
+          ],
+          "properties": {
+            "StructVariant": {
+              "type": "object",
+              "required": [
+                "floats"
+              ],
+              "properties": {
+                "floats": {
+                  "type": "array",
+                  "items": {
+                    "type": "number",
+                    "format": "float"
+                  },
+                  "maxItems": 100,
+                  "minItems": 1
+                }
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}