VienDesu/schemars
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document more attributes

Browse source
This commit is contained in:
Graham Esau 2019-12-24 22:59:26 +00:00
parent 0358a4e141
commit e29f10f6b3
1 changed files with 23 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/1.1-attributes.md
View file

@ -19,17 +19,17 @@ Serde also allows setting `#[serde(...)]` attributes which change how types are
## Table of Contents ## Table of Contents
1. [Supported Serde Attributes](#supported-serde-attributes) 1. [Supported Serde Attributes](#supported-serde-attributes)
1. [`rename`](#rename) - [`rename`](#rename)
1. [`rename_all`](#rename_all) - [`rename_all`](#rename_all)
1. [`tag` / `untagged`](#tag) - [`tag` / `untagged`](#tag)
1. [`default`](#default) - [`default`](#default)
1. [`skip`](#skip) - [`skip`](#skip)
1. [`skip_serializing`](#skip_serializing) - [`skip_serializing`](#skip_serializing)
1. [`skip_deserializing`](#skip_deserializing) - [`skip_deserializing`](#skip_deserializing)
1. [`flatten`](#flatten) - [`flatten`](#flatten)
1. [`with`](#with) - [`with`](#with)
1. [Other Attributes](#other-attributes) 1. [Other Attributes](#other-attributes)
1. [Doc Comments (`doc`)](#doc) - [Doc Comments (`doc`)](#doc)
## Supported Serde Attributes ## Supported Serde Attributes
@ -42,6 +42,8 @@ Serde also allows setting `#[serde(...)]` attributes which change how types are
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 as the schema identifier for schemas referenced from another schema's `$ref` property. 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 as the schema identifier for schemas referenced from another schema's `$ref` property.
If set on a struct or enum with generic type parameters, then the given name may contain them enclosed in curly braces (e.g. `{T}`) and they will be replaced with the concrete type names when the schema is generated.
Serde docs: [container](https://serde.rs/container-attrs.html#rename) / [variant](https://serde.rs/variant-attrs.html#rename) / [field](https://serde.rs/field-attrs.html#rename) Serde docs: [container](https://serde.rs/container-attrs.html#rename) / [variant](https://serde.rs/variant-attrs.html#rename) / [field](https://serde.rs/field-attrs.html#rename)
<h3 id="rename_all"> <h3 id="rename_all">
@ -67,7 +69,7 @@ Serde docs: [`tag`](https://serde.rs/container-attrs.html#tag) / [`untagged`](ht
`#[serde(default)]` / `#[schemars(default)]` / `#[serde(default = "path")]` / `#[schemars(default = "path")]` `#[serde(default)]` / `#[schemars(default)]` / `#[serde(default = "path")]` / `#[schemars(default = "path")]`
</h3> </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 [`#[serde(skip_serializing_if = "..."]`](https://serde.rs/field-attrs.html#skip_serializing_if) attribute on the field. If the field also has a [`#[serde(serialize_with = "..."]`](https://serde.rs/field-attrs.html#serialize_with) property set, then it will be used to serialize the default value. 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.
Serde docs: [container](https://serde.rs/container-attrs.html#default) / [field](https://serde.rs/field-attrs.html#default) Serde docs: [container](https://serde.rs/container-attrs.html#default) / [field](https://serde.rs/field-attrs.html#default)
@ -103,11 +105,19 @@ Serde docs: [variant](https://serde.rs/variant-attrs.html#skip_deserializing) /
`#[serde(flatten)]` / `#[schemars(flatten)]` `#[serde(flatten)]` / `#[schemars(flatten)]`
</h3> </h3>
Set on a field to include that field's contents as though they belonged to the field's container.
Serde docs: [field](https://serde.rs/field-attrs.html#flatten)
<h3 id="with"> <h3 id="with">
`#[serde(with = "module")]` / `#[schemars(with = "module")]` `#[serde(with = "Type")]` / `#[schemars(with = "Type")]`
</h3> </h3>
Set on a field to generate this field's schema as the given type instead of the field's 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`.
Serde docs: [field](https://serde.rs/field-attrs.html#with)
</div> </div>
## Other Attributes ## Other Attributes
@ -117,4 +127,4 @@ Serde docs: [variant](https://serde.rs/variant-attrs.html#skip_deserializing) /
Doc Comments (`#[doc = "..."]`) Doc Comments (`#[doc = "..."]`)
</h3> </h3>
TODO! 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`.