注意

这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。这是 Architect 对 schemars 的分支。

Schemars

从 Rust 代码生成 JSON 模式文档

基本用法

如果您不关心具体细节，生成您的类型 JSON 模式的最简单方法是使用 #[derive(JsonSchema)] 和 schema_for! 宏。类型的所有字段都必须实现 JsonSchema - Schemars 为许多标准库类型实现了此功能。

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> },
}

let schema = schema_for!(MyStruct);
println!("{}", serde_json::to_string_pretty(&schema).unwrap());

{
  "$schema": "https://json-schema.fullstack.org.cn/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": {
      "anyOf": [
        {
          "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
        }
      ]
    }
  }
}

Serde 兼容性

该库的主要目标之一是与 Serde 兼容。任何生成的模式 都应该 与 serde_json 序列化/反序列化到/从 JSON 的方式相匹配。为此，Schemars 将检查从 #[serde(...)] 属性导出的 JsonSchema 类型，并相应地调整生成的模式。

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> },
}

let schema = schema_for!(MyStruct);
println!("{}", serde_json::to_string_pretty(&schema).unwrap());

{
  "$schema": "https://json-schema.fullstack.org.cn/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"
              }
            }
          }
        }
      ]
    }
  }
}

#[serde(...)] 属性可以通过使用 #[schemars(...)] 属性来覆盖，它们的行为相同（例如，#[schemars(rename_all = "camelCase")]）。如果您想要更改生成的模式而不影响 Serde 的行为，或者您根本不使用 Serde，这可能会很有用。

示例值模式

如果您想要一个无法/没有实现 JsonSchema 的类型的模式，但实现了 serde::Serialize，则可以从该类型的值生成 JSON 模式。但是，这种模式通常不如类型实现了 JsonSchema 那么精确 - 尤其是在涉及枚举时，因为 schemars 不会基于单个变体对枚举的结构做出任何假设。

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> },
}

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());

{
  "$schema": "https://json-schema.fullstack.org.cn/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
  }
}

功能标志

• derive（默认启用）- 提供了 #[derive(JsonSchema)] 宏
• impl_json_schema - 为 Schemars 类型本身实现 JsonSchema
• preserve_order - 在 Schema 和 SchemaObject 中保留结构体的字段顺序

Schemars 可以通过功能标志（依赖项版本在括号中显示）在几个流行的 crate 中实现 JsonSchema

• chrono - chrono (^0.4)
• indexmap1 - indexmap (^1.2)
• either - either (^1.3)
• uuid08 - uuid (^0.8)
• uuid1 - uuid (^1.0)
• smallvec - smallvec (^1.0)
• arrayvec05 - arrayvec (^0.5)
• arrayvec07 - arrayvec (^0.7)
• url - url (^2.0)
• bytes - bytes (^1.0)
• enumset - enumset (^1.0)
• rust_decimal - rust_decimal (^1.0)
• bigdecimal - bigdecimal (^0.3)
• smol_str - smol_str (^0.1.17)

例如，要在来自 chrono 的类型上实现 JsonSchema，请在您的 Cargo.toml 中将 schemars 依赖项作为一个功能启用，如下所示

[dependencies]
schemars = { version = "0.8", features = ["chrono"] }