Docs processing - don't break markdown input

docs/_includes/examples/raw_doc_comments.rs

@@ -0,0 +1,44 @@
+use schemars::{gen::SchemaSettings, JsonSchema};
+
+/// # My Amazing Struct
+///
+///This struct shows off generating a schema with
+/// a custom title and description.
+///
+/// Markdown input can be used without a hassle if we enable `raw_description_text` flag:
+///
+/// ```rust
+/// let settings = SchemaSettings::draft07().with(|s| s.raw_description_text = true);
+/// let mut generator = settings.into_generator();
+/// let schema = generator.root_schema_for::<MyStruct>();
+/// ```
+#[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. T
+    StructVariant {
+        /// The floats themselves
+        floats: Vec<f32>,
+    },
+}
+
+fn main() {
+    let settings = SchemaSettings::draft07().with(|s| s.raw_description_text = true);
+    let mut generator = settings.into_generator();
+    let schema = generator.root_schema_for::<MyStruct>();
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

docs/_includes/examples/raw_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\na custom title and description.\n\nMarkdown input can be used without a hassle if we enable `raw_description_text` flag:\n\n```rust\nlet settings = SchemaSettings::draft07().with(|s| s.raw_description_text = true);\nlet mut generator = settings.into_generator();\nlet schema = generator.root_schema_for::<MyStruct>();\n```",
+  "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\nsome floats. T",
+          "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
+        }
+      ]
+    }
+  }
+}

schemars/examples/raw_doc_comments.rs

@@ -0,0 +1,44 @@
+use schemars::{gen::SchemaSettings, JsonSchema};
+
+/// # My Amazing Struct
+///
+///This struct shows off generating a schema with
+/// a custom title and description.
+///
+/// Markdown input can be used without a hassle if we enable `raw_description_text` flag:
+///
+/// ```rust
+/// let settings = SchemaSettings::draft07().with(|s| s.raw_description_text = true);
+/// let mut generator = settings.into_generator();
+/// let schema = generator.root_schema_for::<MyStruct>();
+/// ```
+#[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. T
+    StructVariant {
+        /// The floats themselves
+        floats: Vec<f32>,
+    },
+}
+
+fn main() {
+    let settings = SchemaSettings::draft07().with(|s| s.raw_description_text = true);
+    let mut generator = settings.into_generator();
+    let schema = generator.root_schema_for::<MyStruct>();
+    println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+}

schemars/examples/raw_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\na custom title and description.\n\nMarkdown input can be used without a hassle if we enable `raw_description_text` flag:\n\n```rust\nlet settings = SchemaSettings::draft07().with(|s| s.raw_description_text = true);\nlet mut generator = settings.into_generator();\nlet schema = generator.root_schema_for::<MyStruct>();\n```",
+  "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\nsome floats. T",
+          "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
+        }
+      ]
+    }
+  }
+}

schemars/src/gen.rs

@@ -37,6 +37,12 @@ pub struct SchemaSettings {
     ///
     /// Defaults to `"http://json-schema.org/draft-07/schema#"`.
     pub meta_schema: Option<String>,
+    /// If `true`, raw descriptions will be used in generated schemas.
+    ///
+    /// This option should be set to `true` if markup language is used in descriptions.
+    ///
+    /// Defaults to `false`
+    pub raw_description_text: bool,
     /// A list of visitors that get applied to all generated root schemas.
     pub visitors: Vec<Box<dyn GenVisitor>>,
     /// Inline all subschemas instead of using references.
@@ -64,6 +70,7 @@ impl SchemaSettings {
             meta_schema: Some("http://json-schema.org/draft-07/schema#".to_owned()),
             visitors: vec![Box::new(RemoveRefSiblings)],
             inline_subschemas: false,
+            raw_description_text: false,
             _hidden: (),
         }
     }
@@ -77,6 +84,7 @@ impl SchemaSettings {
             meta_schema: Some("https://json-schema.org/draft/2019-09/schema".to_owned()),
             visitors: Vec::default(),
             inline_subschemas: false,
+            raw_description_text: false,
             _hidden: (),
         }
     }
@@ -101,6 +109,7 @@ impl SchemaSettings {
                 }),
             ],
             inline_subschemas: false,
+            raw_description_text: false,
             _hidden: (),
         }
     }

schemars/tests/docs.rs

@@ -89,3 +89,37 @@ struct OverrideDocs {
 fn doc_comments_override() -> TestResult {
     test_default_generated_schema::<OverrideDocs>("doc_comments_override")
 }
+
+/// # RawDescriptionText struct
+///
+/// This struct is commented using markdown.
+///
+/// ## Example
+///
+/// A code:
+///
+/// ```
+/// let _json = serde_json::to_string(&MarkupDocs { my_int: 10 }).unwrap();
+/// ```
+///
+/// A table:
+///
+/// | Col1     | Col2     |
+/// |----------|----------|
+/// | schemars | schemars |
+/// | serde    | serde    |
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+struct RawDescriptionText {
+    /// # Documented field
+    ///
+    /// This is first line of a description
+    /// This is second line of a description
+    my_int: i32,
+}
+
+#[test]
+fn raw_description_text() -> TestResult {
+    let settings = SchemaSettings::draft07().with(|s| s.raw_description_text = true);
+    test_generated_schema::<RawDescriptionText>("raw_description_text", settings)
+}

schemars/tests/expected/raw_description_text.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "RawDescriptionText struct",
+  "description": "This struct is commented using markdown.\n\n## Example\n\nA code:\n\n```\nlet _json = serde_json::to_string(&MarkupDocs { my_int: 10 }).unwrap();\n```\n\nA table:\n\n| Col1     | Col2     |\n|----------|----------|\n| schemars | schemars |\n| serde    | serde    |",
+  "type": "object",
+  "required": [
+    "my_int"
+  ],
+  "properties": {
+    "my_int": {
+      "title": "Documented field",
+      "description": "This is first line of a description\nThis is second line of a description",
+      "type": "integer",
+      "format": "int32"
+    }
+  }
+}