From f387a0ec56888d242243cdcc4e343772fd9f4516 Mon Sep 17 00:00:00 2001 From: Graham Esau Date: Thu, 26 Dec 2019 21:34:08 +0000 Subject: [PATCH] Add examples to docs --- docs/_includes/example.md | 14 ++++ docs/_includes/examples/main.rs | 21 ++++++ docs/_includes/examples/main.schema.json | 69 +++++++++++++++++++ docs/_includes/examples/serde_attrs.rs | 26 +++++++ .../examples/serde_attrs.schema.json | 53 ++++++++++++++ docs/_sass/overrides.scss | 5 ++ docs/examples/1-derive_jsonschema.md | 13 ++++ docs/examples/2-serde_attrs.md | 15 ++++ docs/examples/example1.md | 9 --- docs/examples/example2.md | 8 --- update-examples.sh | 7 ++ 11 files changed, 223 insertions(+), 17 deletions(-) create mode 100644 docs/_includes/example.md create mode 100644 docs/_includes/examples/main.rs create mode 100644 docs/_includes/examples/main.schema.json create mode 100644 docs/_includes/examples/serde_attrs.rs create mode 100644 docs/_includes/examples/serde_attrs.schema.json create mode 100644 docs/examples/1-derive_jsonschema.md create mode 100644 docs/examples/2-serde_attrs.md delete mode 100644 docs/examples/example1.md delete mode 100644 docs/examples/example2.md diff --git a/docs/_includes/example.md b/docs/_includes/example.md new file mode 100644 index 0000000..aca27b3 --- /dev/null +++ b/docs/_includes/example.md @@ -0,0 +1,14 @@ +{% capture input %}examples/{{ include.name }}.rs{% endcapture %} +{% capture output %}examples/{{ include.name }}.schema.json{% endcapture %} + +```rust +{% include {{ input }} %} +``` + +
+Click to see the output JSON schema... + +```json +{% include {{ output }} %} +``` +
diff --git a/docs/_includes/examples/main.rs b/docs/_includes/examples/main.rs new file mode 100644 index 0000000..8bcc7ed --- /dev/null +++ b/docs/_includes/examples/main.rs @@ -0,0 +1,21 @@ +use schemars::{schema_for, JsonSchema}; + +#[derive(JsonSchema)] +pub struct MyStruct { + pub my_int: i32, + pub my_bool: bool, + pub my_nullable_enum: Option, +} + +#[derive(JsonSchema)] +pub enum MyEnum { + StringNewType(String), + StructVariant { + floats: Vec, + } +} + +fn main() { + let schema = schema_for!(MyStruct); + println!("{}", serde_json::to_string_pretty(&schema).unwrap()); +} diff --git a/docs/_includes/examples/main.schema.json b/docs/_includes/examples/main.schema.json new file mode 100644 index 0000000..ec883fd --- /dev/null +++ b/docs/_includes/examples/main.schema.json @@ -0,0 +1,69 @@ +{ + "$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" + }, + "my_nullable_enum": { + "anyOf": [ + { + "$ref": "#/definitions/MyEnum" + }, + { + "type": "null" + } + ] + } + }, + "definitions": { + "MyEnum": { + "anyOf": [ + { + "type": "object", + "required": [ + "StringNewType" + ], + "properties": { + "StringNewType": { + "type": "string" + } + } + }, + { + "type": "object", + "required": [ + "StructVariant" + ], + "properties": { + "StructVariant": { + "type": "object", + "required": [ + "floats" + ], + "properties": { + "floats": { + "type": "array", + "items": { + "type": "number", + "format": "float" + } + } + } + } + } + } + ] + } + } +} diff --git a/docs/_includes/examples/serde_attrs.rs b/docs/_includes/examples/serde_attrs.rs new file mode 100644 index 0000000..cc612e9 --- /dev/null +++ b/docs/_includes/examples/serde_attrs.rs @@ -0,0 +1,26 @@ +use schemars::{schema_for, JsonSchema}; +use serde::{Deserialize, Serialize}; + +#[derive(Deserialize, Serialize, JsonSchema)] +#[serde(rename_all = "camelCase")] +pub struct MyStruct { + #[serde(rename = "myNumber")] + pub my_int: i32, + pub my_bool: bool, + #[serde(default)] + pub my_nullable_enum: Option, +} + +#[derive(Deserialize, Serialize, JsonSchema)] +#[serde(untagged)] +pub enum MyEnum { + StringNewType(String), + StructVariant { + floats: Vec, + } +} + +fn main() { + let schema = schema_for!(MyStruct); + println!("{}", serde_json::to_string_pretty(&schema).unwrap()); +} diff --git a/docs/_includes/examples/serde_attrs.schema.json b/docs/_includes/examples/serde_attrs.schema.json new file mode 100644 index 0000000..f7e6ac9 --- /dev/null +++ b/docs/_includes/examples/serde_attrs.schema.json @@ -0,0 +1,53 @@ +{ + "$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" + } + }, + "definitions": { + "MyEnum": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "object", + "required": [ + "floats" + ], + "properties": { + "floats": { + "type": "array", + "items": { + "type": "number", + "format": "float" + } + } + } + } + ] + } + } +} diff --git a/docs/_sass/overrides.scss b/docs/_sass/overrides.scss index a7e42cc..8ad4259 100644 --- a/docs/_sass/overrides.scss +++ b/docs/_sass/overrides.scss @@ -47,4 +47,9 @@ code { h1, h2, h3, h4, h5, h6 { margin-left: -20px; } +} + +details summary { + display: list-item; + cursor: pointer; } \ No newline at end of file diff --git a/docs/examples/1-derive_jsonschema.md b/docs/examples/1-derive_jsonschema.md new file mode 100644 index 0000000..3bf4548 --- /dev/null +++ b/docs/examples/1-derive_jsonschema.md @@ -0,0 +1,13 @@ +--- +layout: default +title: Deriving JsonSchema +parent: Examples +nav_order: 1 +summary: Deriving JsonSchema on a struct and enum. +--- + +# Deriving JsonSchema + +This is the simplest usage of Schemars. Both types are made to derive `JsonSchema`, and the `schema_for!` macro is used to generate the schema itself. + +{% include example.md name="main" %} diff --git a/docs/examples/2-serde_attrs.md b/docs/examples/2-serde_attrs.md new file mode 100644 index 0000000..7fcc379 --- /dev/null +++ b/docs/examples/2-serde_attrs.md @@ -0,0 +1,15 @@ +--- +layout: default +title: Using Serde Attributes +parent: Examples +nav_order: 2 +summary: 'Deriving JsonSchema on types that use #[serde] attributes to customise serialization behaviour.' +--- + +# Using Serde Attributes + +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. + +The list of supported `#[serde]` attributes are [documented here]({{ site.baseurl }}/deriving/attributes/#supported-serde-attributes). + +{% include example.md name="serde_attrs" %} diff --git a/docs/examples/example1.md b/docs/examples/example1.md deleted file mode 100644 index 0652db1..0000000 --- a/docs/examples/example1.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Example 1 -parent: Examples -nav_order: 1 -summary: blah blah blahhh ---- - -# Examples 1: A Meta-Example \ No newline at end of file diff --git a/docs/examples/example2.md b/docs/examples/example2.md deleted file mode 100644 index 05d71e2..0000000 --- a/docs/examples/example2.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -layout: default -title: Example 2 -parent: Examples -nav_order: 2 ---- - -# Examples 2: Another Meta-Example \ No newline at end of file diff --git a/update-examples.sh b/update-examples.sh index bd77355..55dd676 100644 --- a/update-examples.sh +++ b/update-examples.sh @@ -10,3 +10,10 @@ do example=${file%.rs} cargo run --example "$example" > "$example.schema.json" done + +cd ../.. + +rm -f docs/_includes/examples/*.rs +rm -f docs/_includes/examples/*.schema.json + +cp schemars/examples/* docs/_includes/examples/