Apistos Schemars

从 Rust 代码生成 JSON 模式文档

⚠️ 警告

这是官方 schemars 仓库 的一个分支，它只存在于 这个 PR 被合并之前。它以 apistos-schemars 和 apistos-schemars_derive 的名称发布在 crates.io 上。这个分支基于 schemars master，并定期重置。

基本用法

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

extern crate apistos_schemars as 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.org/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(...)] 属性，并相应地调整生成的模式。

extern crate apistos_schemars as schemars;
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.org/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 不会根据单个变体对枚举的结构做出任何假设。

extern crate apistos_schemars as 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": "http://json-schema.org/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)] 宏
• preserve_order - 保持结构体字段在 Schema 属性中的顺序
• raw_value - 实现 JsonSchema 对于 serde_json::value::RawValue（启用 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)
• ipnetwork - ipnetwork (^0.20)
• 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.2", features = ["chrono04"] }