Schemars

[!注意] 此分支是 Schemars 当前 v1 alpha 版本的分支，仍在开发中。对于 Schemars 当前稳定版本 (v0.8.x)，请参阅 v0 分支。

有关从 0.8 迁移到 1.0 的信息，请参阅 迁移指南。

从 Rust 代码生成 JSON Schema 文档

基本用法

如果您不关心具体细节，为您的类型生成 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/2020-12/schema",
  "title": "MyStruct",
  "type": "object",
  "properties": {
    "my_bool": {
      "type": "boolean"
    },
    "my_int": {
      "type": "integer",
      "format": "int32"
    },
    "my_nullable_enum": {
      "anyOf": [
        {
          "$ref": "#/$defs/MyEnum"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": ["my_int", "my_bool"],
  "$defs": {
    "MyEnum": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "StringNewType": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": ["StringNewType"]
        },
        {
          "type": "object",
          "properties": {
            "StructVariant": {
              "type": "object",
              "properties": {
                "floats": {
                  "type": "array",
                  "items": {
                    "type": "number",
                    "format": "float"
                  }
                }
              },
              "required": ["floats"]
            }
          },
          "additionalProperties": false,
          "required": ["StructVariant"]
        }
      ]
    }
  }
}

Serde 兼容性

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

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/2020-12/schema",
  "title": "MyStruct",
  "type": "object",
  "properties": {
    "myBool": {
      "type": "boolean"
    },
    "myNullableEnum": {
      "anyOf": [
        {
          "$ref": "#/$defs/MyEnum"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "myNumber": {
      "type": "integer",
      "format": "int32"
    }
  },
  "additionalProperties": false,
  "required": ["myNumber", "myBool"],
  "$defs": {
    "MyEnum": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "properties": {
            "floats": {
              "type": "array",
              "items": {
                "type": "number",
                "format": "float"
              }
            }
          },
          "required": ["floats"]
        }
      ]
    }
  }
}

使用 #[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
  }
}

功能标志

• std（默认启用）——为 rust 标准库中的类型实现 JsonSchema（即使禁用了此功能，JsonSchema 仍然在 core 和 alloc 中的类型上实现）。禁用此功能以在 no_std 环境中使用 schemars。
• derive（默认启用）——提供 #[derive(JsonSchema)] 宏
• preserve_order——在 Schema 属性中保持结构体的字段顺序
• raw_value——为 serde_json::value::RawValue 实现 JsonSchema（启用 serde_json 的 raw_value 功能）

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

• arrayvec07 - arrayvec (^0.7)
• bigdecimal04 - bigdecimal (^0.4)
• bytes1 - bytes (^1.0)
• chrono04 - chrono (^0.4)
• either1 - either (^1.3)
• enumset1 - enumset (^1.0)
• indexmap2 - indexmap (^2.0)
• rust_decimal1 - rust_decimal (^1.0)
• semver1 - semver (^1.0.9)
• smallvec1 - smallvec (^1.0)
• smol_str02 - smol_str (^0.2.1)
• url2 - url (^2.0)
• uuid1 - uuid (^1.0)

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

[dependencies]
schemars = { version = "1.0.0-alpha.11", features = ["chrono04"] }