schemars

schemars

根据 Rust 类型生成 JSON Schema。

crate	作用
serde	定义 Rust 类型如何序列化 / 反序列化
serde_json	把 Rust 数据和 JSON 字符串互转
schemars	根据 Rust 类型生成 JSON Schema，用来描述/校验 JSON 结构

serde/serde_json

serde/serde_json只能转换

输出

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct User {
    name: String,
    age: u8,
    email: Option<String>,
    phone: Option<String>,
}

fn main() {
    let user = User {
        name: "Tom".to_string(),
        age: 29,
        email: None,
        phone: None,
    };
    // 转为String
    let json = serde_json::to_string(&user).expect("转换str失败");
    println!("json: {}", json);
}

json: {"name":"Tom","age":29,"email":null,"phone":null}

输入

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct User {
    name: String,
    age: u8,
    email: Option<String>,
    phone: Option<String>,
}

fn main() {
    let user: User = serde_json::from_str(r#"{"name":"Alice","age":18}"#).expect("转为User失败");
    println!("user: {:?}", user);
}

user: User { name: "Alice", age: 18, email: None, phone: None }

schemars

schemars 负责生成 JSON Schema

• 用途
  • 生成接口文档
  • OpenAPI/Swagger
  • 配置文件校验
  • 给前端生成类型依据
  • LLM/Function Calling/Tool Schema
• 输出
  • json: serde + serde_json
  • yaml: serde + serde_yaml

use serde::{Deserialize, Serialize};
use schemars::{schema_for, JsonSchema};

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
struct User {
    name: String,
    age: u8,
    email: Option<String>,
    phone: Option<String>,
}

fn main() {
    // 是一个schema对象
    let schema = schema_for!(User);
    // 把schema转为String
    // to_string_pretty是美化输出
    let schema_str = serde_json::to_string_pretty(&schema).expect("转换失败");
    println!("schema_str: {}", schema_str);
}

输出内容

• "$schema":使用的是哪个JSON Schema规范版本
• title:表示这个Schema的标题。一般来自 Rust 结构体名：
• type:表示这个 JSON 必须是对象
• properties: 表示对象里有哪些字段，以及每个字段的类型和约束
• required: 表示必填字段

schema_str: {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "properties": {
    "age": {
      "type": "integer",
      "format": "uint8",
      "maximum": 255,
      "minimum": 0
    },
    "email": {
      "type": [
        "string",
        "null"
      ]
    },
    "name": {
      "type": "string"
    },
    "phone": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "name",
    "age"
  ]
}