diff --git a/schemars/src/lib.rs b/schemars/src/lib.rs index 796ec272..9905b01a 100644 --- a/schemars/src/lib.rs +++ b/schemars/src/lib.rs @@ -1,287 +1,5 @@ #![forbid(unsafe_code)] -/*! -Generate JSON Schema documents from Rust code - -## Basic Usage - -If you don't really care about the specifics, the easiest way to generate a JSON schema for your types is to `#[derive(JsonSchema)]` and use the `schema_for!` macro. All fields of the type must also implement `JsonSchema` - Schemars implements this for many standard library types. - -```rust -use schemars::{schema_for, JsonSchema}; - -#[derive(JsonSchema)] -pub struct MyStruct { - pub my_int: i32, - pub my_bool: bool, - pub my_nullable_enum: Option, -} - -#[derive(JsonSchema)] -pub enum MyEnum { - StringNewType(String), - StructVariant { floats: Vec }, -} - -let schema = schema_for!(MyStruct); -println!("{}", serde_json::to_string_pretty(&schema).unwrap()); -``` - -
-Click to see the output JSON schema... - -```json -{ - "$schema": "http://json-schema.org/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 Compatibility - -One of the main aims of this library is compatibility with [Serde](https://github.com/serde-rs/serde). Any generated schema *should* match how [serde_json](https://github.com/serde-rs/json) would serialize/deserialize to/from JSON. To support this, Schemars will check for any `#[serde(...)]` attributes on types that derive `JsonSchema`, and adjust the generated schema accordingly. - -```rust -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, -} - -#[derive(Deserialize, Serialize, JsonSchema)] -#[serde(untagged)] -pub enum MyEnum { - StringNewType(String), - StructVariant { floats: Vec }, -} - -let schema = schema_for!(MyStruct); -println!("{}", serde_json::to_string_pretty(&schema).unwrap()); -``` - -
-Click to see the output JSON schema... - -```json -{ - "$schema": "http://json-schema.org/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(...)]` attributes can be overriden using `#[schemars(...)]` attributes, which behave identically (e.g. `#[schemars(rename_all = "camelCase")]`). You may find this useful if you want to change the generated schema without affecting Serde's behaviour, or if you're just not using Serde. - -### Schema from Example Value - -If you want a schema for a type that can't/doesn't implement `JsonSchema`, but does implement `serde::Serialize`, then you can generate a JSON schema from a value of that type. However, this schema will generally be less precise than if the type implemented `JsonSchema` - particularly when it involves enums, since schemars will not make any assumptions about the structure of an enum based on a single variant. - -```rust -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, -} - -#[derive(Serialize)] -pub enum MyEnum { - StringNewType(String), - StructVariant { floats: Vec }, -} - -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()); -``` - -
-Click to see the output JSON schema... - -```json -{ - "$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 - } -} -``` -
- -## Feature Flags -- `derive` (enabled by default) - provides `#[derive(JsonSchema)]` macro -- `impl_json_schema` - implements `JsonSchema` for Schemars types themselves -- `preserve_order` - keep the order of struct fields in `Schema` and `SchemaObject` - -Schemars can implement `JsonSchema` on types from several popular crates, enabled via feature flags (dependency versions are shown in brackets): -- `chrono` - [chrono](https://crates.io/crates/chrono) (^0.4) -- `indexmap1` - [indexmap](https://crates.io/crates/indexmap) (^1.2) -- `either` - [either](https://crates.io/crates/either) (^1.3) -- `uuid08` - [uuid](https://crates.io/crates/uuid) (^0.8) -- `uuid1` - [uuid](https://crates.io/crates/uuid) (^1.0) -- `smallvec` - [smallvec](https://crates.io/crates/smallvec) (^1.0) -- `arrayvec05` - [arrayvec](https://crates.io/crates/arrayvec) (^0.5) -- `arrayvec07` - [arrayvec](https://crates.io/crates/arrayvec) (^0.7) -- `url` - [url](https://crates.io/crates/url) (^2.0) -- `bytes` - [bytes](https://crates.io/crates/bytes) (^1.0) -- `enumset` - [enumset](https://crates.io/crates/enumset) (^1.0) -- `rust_decimal` - [rust_decimal](https://crates.io/crates/rust_decimal) (^1.0) -- `bigdecimal` - [bigdecimal](https://crates.io/crates/bigdecimal) (^0.3) -- `smol_str` - [smol_str](https://crates.io/crates/smol_str) (^0.1.17) - -For example, to implement `JsonSchema` on types from `chrono`, enable it as a feature in the `schemars` dependency in your `Cargo.toml` like so: - -```toml -[dependencies] -schemars = { version = "0.8", features = ["chrono"] } -``` -*/ +#![doc = include_str!("../README.md")] /// The map type used by schemars types. /// diff --git a/schemars/src/schema.rs b/schemars/src/schema.rs index 01fce865..4bef66e0 100644 --- a/schemars/src/schema.rs +++ b/schemars/src/schema.rs @@ -231,7 +231,7 @@ impl SchemaObject { self.reference.is_some() } - /// Returns `true` if `self` accepts values of the given type, according to the [`instance_type`] field. + /// Returns `true` if `self` accepts values of the given type, according to the [`instance_type`](struct.SchemaObject.html#structfield.instance_type) field. /// /// This is a basic check that always returns `true` if no `instance_type` is specified on the schema, /// and does not check any subschemas. Because of this, both `{}` and `{"not": {}}` accept any type according