Add separate docs for v0.8/v1
This commit is contained in:
Graham Esau
parent
3150f98fc8
commit
d511d447f7
61 changed files with 1620 additions and 58 deletions
|
|
@ -1,5 +1,4 @@
|
|||
---
|
||||
layout: default
|
||||
title: Attributes
|
||||
parent: Deriving JsonSchema
|
||||
nav_order: 1
|
||||
|
|
@ -26,30 +25,31 @@ TABLE OF CONTENTS
|
|||
</summary>
|
||||
|
||||
1. [Supported Serde Attributes](#supported-serde-attributes)
|
||||
- [`rename`](#rename)
|
||||
- [`rename_all`](#rename_all)
|
||||
- [`tag` / `content` / `untagged`](#tag)
|
||||
- [`default`](#default)
|
||||
- [`skip`](#skip)
|
||||
- [`skip_serializing`](#skip_serializing)
|
||||
- [`skip_deserializing`](#skip_deserializing)
|
||||
- [`flatten`](#flatten)
|
||||
- [`with`](#with)
|
||||
- [`bound`](#bound)
|
||||
- [`rename`](#rename)
|
||||
- [`rename_all`](#rename_all)
|
||||
- [`tag` / `content` / `untagged`](#tag)
|
||||
- [`default`](#default)
|
||||
- [`skip`](#skip)
|
||||
- [`skip_serializing`](#skip_serializing)
|
||||
- [`skip_deserializing`](#skip_deserializing)
|
||||
- [`flatten`](#flatten)
|
||||
- [`with`](#with)
|
||||
- [`bound`](#bound)
|
||||
1. [Supported Validator Attributes](#supported-validator-attributes)
|
||||
- [`email` / `phone` / `url`](#email-phone-url)
|
||||
- [`length`](#length)
|
||||
- [`range`](#range)
|
||||
- [`regex`](#regex)
|
||||
- [`contains`](#contains)
|
||||
- [`required` / `required_nested`](#required)
|
||||
- [`email` / `phone` / `url`](#email-phone-url)
|
||||
- [`length`](#length)
|
||||
- [`range`](#range)
|
||||
- [`regex`](#regex)
|
||||
- [`contains`](#contains)
|
||||
- [`required` / `required_nested`](#required)
|
||||
1. [Other Attributes](#other-attributes)
|
||||
- [`schema_with`](#schema_with)
|
||||
- [`title` / `description`](#title-description)
|
||||
- [`example`](#example)
|
||||
- [`deprecated`](#deprecated)
|
||||
- [`crate`](#crate)
|
||||
- [Doc Comments (`doc`)](#doc)
|
||||
- [`schema_with`](#schema_with)
|
||||
- [`title` / `description`](#title-description)
|
||||
- [`example`](#example)
|
||||
- [`deprecated`](#deprecated)
|
||||
- [`crate`](#crate)
|
||||
- [Doc Comments (`doc`)](#doc)
|
||||
|
||||
</details>
|
||||
|
||||
## Supported Serde Attributes
|
||||
|
|
@ -59,6 +59,7 @@ TABLE OF CONTENTS
|
|||
<h3 id="rename">
|
||||
|
||||
`#[serde(rename = "name")]` / `#[schemars(rename = "name")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a struct, enum, field or variant to use the given name in the generated schema instead of the Rust name. When used on a struct or enum, the given name will be used as the title for root schemas, and the key within the root's `definitions` property for subschemas.
|
||||
|
|
@ -70,6 +71,7 @@ Serde docs: [container](https://serde.rs/container-attrs.html#rename) / [variant
|
|||
<h3 id="rename_all">
|
||||
|
||||
`#[serde(rename_all = "...")]` / `#[schemars(rename_all = "...")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a struct, enum or variant to rename all fields according to the given case convention (see the Serde docs for details).
|
||||
|
|
@ -81,6 +83,7 @@ Serde docs: [container](https://serde.rs/container-attrs.html#rename_all) / [var
|
|||
`#[serde(tag = "type")]` / `#[schemars(tag = "type")]` <br />
|
||||
`#[serde(tag = "t", content = "c")]` / `#[schemars(tag = "t", content = "c")]` <br />
|
||||
`#[serde(untagged)]` / `#[schemars(untagged)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on an enum to generate the schema for the [internally tagged](https://serde.rs/enum-representations.html#internally-tagged), [adjacently tagged](https://serde.rs/enum-representations.html#adjacently-tagged), or [untagged](https://serde.rs/enum-representations.html#untagged) representation of this enum.
|
||||
|
|
@ -90,6 +93,7 @@ Serde docs: [`tag`](https://serde.rs/container-attrs.html#tag) / [`tag`+`content
|
|||
<h3 id="default">
|
||||
|
||||
`#[serde(default)]` / `#[schemars(default)]` / `#[serde(default = "path")]` / `#[schemars(default = "path")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a struct or field to give fields a default value, which excludes them from the schema's `required` properties. The default will also be set on the field's schema's `default` property, unless it is skipped by a [`skip_serializing_if`](https://serde.rs/field-attrs.html#skip_serializing_if) attribute on the field. Any [`serialize_with`](https://serde.rs/field-attrs.html#serialize_with) or [`with`](https://serde.rs/field-attrs.html#with) attribute set on the field will be used to serialize the default value.
|
||||
|
|
@ -99,6 +103,7 @@ Serde docs: [container](https://serde.rs/container-attrs.html#default) / [field]
|
|||
<h3 id="skip">
|
||||
|
||||
`#[serde(skip)]` / `#[schemars(skip)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a variant or field to prevent it from appearing in any generated schema.
|
||||
|
|
@ -108,6 +113,7 @@ Serde docs: [variant](https://serde.rs/variant-attrs.html#skip) / [field](https:
|
|||
<h3 id="skip_serializing">
|
||||
|
||||
`#[serde(skip_serializing)]` / `#[schemars(skip_serializing)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a field of a (non-tuple) struct to set the `writeOnly` property on that field's schema. Serde also allows this attribute on variants or tuple struct fields, but this will have no effect on generated schemas.
|
||||
|
|
@ -117,6 +123,7 @@ Serde docs: [field](https://serde.rs/field-attrs.html#skip_deserializing)
|
|||
<h3 id="skip_deserializing">
|
||||
|
||||
`#[serde(skip_deserializing)]` / `#[schemars(skip_deserializing)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a variant or field. When set on a field of a (non-tuple) struct, that field's schema will have the `readOnly` property set. When set on a variant or tuple struct field Schemars will treat this the same as a [`skip`](#skip) attribute.
|
||||
|
|
@ -126,6 +133,7 @@ Serde docs: [variant](https://serde.rs/variant-attrs.html#skip_deserializing) /
|
|||
<h3 id="flatten">
|
||||
|
||||
`#[serde(flatten)]` / `#[schemars(flatten)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a field to include that field's contents as though they belonged to the field's container.
|
||||
|
|
@ -135,6 +143,7 @@ Serde docs: [field](https://serde.rs/field-attrs.html#flatten)
|
|||
<h3 id="with">
|
||||
|
||||
`#[serde(with = "Type")]` / `#[schemars(with = "Type")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a variant or field to generate its schema as the given type instead of its actual type. Serde allows the `with` attribute to refer to any module path, but Schemars requires this to be an actual type which implements `JsonSchema`.
|
||||
|
|
@ -146,6 +155,7 @@ Serde docs: [variant](https://serde.rs/variant-attrs.html#with) / [field](https:
|
|||
<h3 id="deny_unknown_fields">
|
||||
|
||||
`#[serde(deny_unknown_fields)]` / `#[schemars(deny_unknown_fields)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Setting this on a container will set the `additionalProperties` keyword on generated schemas to `false` to show that any extra properties are explicitly disallowed.
|
||||
|
|
@ -155,6 +165,7 @@ Serde docs: [container](https://serde.rs/container-attrs.html#deny_unknown_field
|
|||
<h3 id="transparent">
|
||||
|
||||
`#[serde(transparent)]` / `#[schemars(transparent)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a newtype struct or a braced struct with one field to make the struct's generated schema exactly the same as that of the single field's.
|
||||
|
|
@ -164,6 +175,7 @@ Serde docs: [container](https://serde.rs/container-attrs.html#transparent)
|
|||
<h3 id="bound">
|
||||
|
||||
`#[schemars(bound = "...")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Where-clause for the JsonSchema impl. This replaces any trait bounds inferred by schemars. Schemars does **not** use trait bounds from `#[serde(bound)]` attributes.
|
||||
|
|
@ -181,6 +193,7 @@ Serde docs: [container](https://serde.rs/container-attrs.html#bound)
|
|||
`#[validate(email)]` / `#[schemars(email)]`<br />
|
||||
`#[validate(phone)]` / `#[schemars(phone)]`<br />
|
||||
`#[validate(url)]` / `#[schemars(url)]`
|
||||
|
||||
</h3>
|
||||
|
||||
Sets the schema's `format` to `email`/`phone`/`uri`, as appropriate. Only one of these attributes may be present on a single field.
|
||||
|
|
@ -191,6 +204,7 @@ Validator docs: [email](https://github.com/Keats/validator#email) / [phone](http
|
|||
|
||||
`#[validate(length(min = 1, max = 10))]` / `#[schemars(length(min = 1, max = 10))]`<br />
|
||||
`#[validate(length(equal = 10))]` / `#[schemars(length(equal = 10))]`
|
||||
|
||||
</h3>
|
||||
|
||||
Sets the `minLength`/`maxLength` properties for string schemas, or the `minItems`/`maxItems` properties for array schemas.
|
||||
|
|
@ -200,6 +214,7 @@ Validator docs: [length](https://github.com/Keats/validator#length)
|
|||
<h3 id="range">
|
||||
|
||||
`#[validate(range(min = 1, max = 10))]` / `#[schemars(range(min = 1, max = 10))]`
|
||||
|
||||
</h3>
|
||||
|
||||
Sets the `minimum`/`maximum` properties for number schemas.
|
||||
|
|
@ -210,6 +225,7 @@ Validator docs: [range](https://github.com/Keats/validator#range)
|
|||
|
||||
`#[validate(regex = "path::to::regex")]` / `#[schemars(regex = "path::to::regex")]`<br />
|
||||
`#[schemars(regex(pattern = r"^\d+$"))]`
|
||||
|
||||
</h3>
|
||||
|
||||
Sets the `pattern` property for string schemas. The `path::to::regex` will typically refer to a [`Regex`](https://docs.rs/regex/*/regex/struct.Regex.html) instance, but Schemars allows it to be any value with a `to_string()` method.
|
||||
|
|
@ -221,6 +237,7 @@ Validator docs: [regex](https://github.com/Keats/validator#regex)
|
|||
<h3 id="contains">
|
||||
|
||||
`#[validate(contains = "string")]` / `#[schemars(contains = "string")]`
|
||||
|
||||
</h3>
|
||||
|
||||
For string schemas, sets the `pattern` property to the given value, with any regex special characters escaped. For object schemas (e.g. when the attribute is set on a HashMap field), includes the value in the `required` property, indicating that the map must contain it as a key.
|
||||
|
|
@ -231,6 +248,7 @@ Validator docs: [contains](https://github.com/Keats/validator#contains)
|
|||
|
||||
`#[validate(required)]` / `#[schemars(required)]`<br />
|
||||
`#[validate(required_nested)]`
|
||||
|
||||
</h3>
|
||||
|
||||
When set on an `Option<T>` field, this will create a schemas as though the field were a `T`.
|
||||
|
|
@ -244,6 +262,7 @@ Validator docs: [required](https://github.com/Keats/validator#required) / [requi
|
|||
<h3 id="schema_with">
|
||||
|
||||
`#[schemars(schema_with = "some::function")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a variant or field to generate this field's schema using the given function. This function must be callable as `fn(&mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema`.
|
||||
|
|
@ -251,6 +270,7 @@ Set on a variant or field to generate this field's schema using the given functi
|
|||
<h3 id="title-description">
|
||||
|
||||
`#[schemars(title = "Some title", description = "Some description")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a container, variant or field to set the generated schema's `title` and/or `description`. If present, these will be used instead of values from any [`doc` comments/attributes](#doc).
|
||||
|
|
@ -258,6 +278,7 @@ Set on a container, variant or field to set the generated schema's `title` and/o
|
|||
<h3 id="example">
|
||||
|
||||
`#[schemars(example = "some::function")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set on a container, variant or field to include the result of the given function in the generated schema's `examples`. The function should take no parameters and can return any type that implements serde's `Serialize` trait - it does not need to return the same type as the attached struct/field. This attribute can be repeated to specify multiple examples.
|
||||
|
|
@ -265,6 +286,7 @@ Set on a container, variant or field to include the result of the given function
|
|||
<h3 id="deprecated">
|
||||
|
||||
`#[deprecated]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set the Rust built-in [`deprecated`](https://doc.rust-lang.org/edition-guide/rust-2018/the-compiler/an-attribute-for-deprecation.html) attribute on a struct, enum, field or variant to set the generated schema's `deprecated` keyword to `true`.
|
||||
|
|
@ -272,6 +294,7 @@ Set the Rust built-in [`deprecated`](https://doc.rust-lang.org/edition-guide/rus
|
|||
<h3 id="crate">
|
||||
|
||||
`#[schemars(crate = "other_crate::schemars")]`
|
||||
|
||||
</h3>
|
||||
|
||||
Set the path to the schemars crate instance the generated code should depend on. This is mostly useful for other crates that depend on schemars in their macros.
|
||||
|
|
@ -279,6 +302,7 @@ Set the path to the schemars crate instance the generated code should depend on.
|
|||
<h3 id="inner">
|
||||
|
||||
`#[schemars(inner(...))]`
|
||||
|
||||
</h3>
|
||||
|
||||
Sets properties specified by [validator attributes](#supported-validator-attributes) on items of an array schema. For example:
|
||||
|
|
@ -293,6 +317,7 @@ struct Struct {
|
|||
<h3 id="doc">
|
||||
|
||||
Doc Comments (`#[doc = "..."]`)
|
||||
|
||||
</h3>
|
||||
|
||||
If a struct, variant or field has any [doc comments](https://doc.rust-lang.org/stable/rust-by-example/meta/doc.html#doc-comments) (or [`doc` attributes](https://doc.rust-lang.org/rustdoc/the-doc-attribute.html)), then these will be used as the generated schema's `description`. If the first line is an ATX-style markdown heading (i.e. it begins with a # character), then it will be used as the schema's `title`, and the remaining lines will be the `description`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue