Update changelog and docs

This commit is contained in:
Graham Esau 2021-09-18 23:00:14 +01:00
parent cec8751c82
commit 1d3541b4b1
2 changed files with 80 additions and 1 deletions

View file

@ -16,7 +16,9 @@ h3 code {
You can add attributes to your types to customize Schemars's derived `JsonSchema` implementation.
Serde also allows setting `#[serde(...)]` attributes which change how types are serialized, and Schemars will generally respect these attributes to ensure that generated schemas will match how the type is serialized by serde_json. `#[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.
[Serde](https://serde.rs/) allows setting `#[serde(...)]` attributes which change how types are serialized, and Schemars will generally respect these attributes to ensure that generated schemas will match how the type is serialized by serde_json. `#[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.
[Validator](https://github.com/Keats/validator) allows setting `#[validate(...)]` attributes to restrict valid values of particular fields, many of which will be used by Schemars to generate more accurate schemas. These can also be overridden by `#[schemars(...)]` attributes.
<details open>
<summary style="font-weight: bold">
@ -33,6 +35,13 @@ TABLE OF CONTENTS
- [`skip_deserializing`](#skip_deserializing)
- [`flatten`](#flatten)
- [`with`](#with)
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)
1. [Other Attributes](#other-attributes)
- [`schema_with`](#schema_with)
- [`title` / `description`](#title-description)
@ -153,6 +162,75 @@ Serde docs: [container](https://serde.rs/container-attrs.html#transparent)
</div>
## Supported Validator Attributes
*These attributes will be processed in Schemars v0.8.4*
<div class="indented">
<h3 id="email-phone-url">
`#[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.
Validator docs: [email](https://github.com/Keats/validator#email) / [phone](https://github.com/Keats/validator#phone) / [url](https://github.com/Keats/validator#url)
<h3 id="length">
`#[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.
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.
Validator docs: [range](https://github.com/Keats/validator#range)
<h3 id="regex">
`#[validate(regex = "path::to::regex")]` / `#[schemars(regex = "path::to::regex")]`
`#[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.
Providing an inline regex pattern using `regex(pattern = ...)` is a Schemars extension, and not currently supported by the Validator crate. When using this form, you may want to use a `r"raw string literal"` so that `\\` characters in the regex pattern are not interpreted as escape sequences in the string.
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.
Validator docs: [contains](https://github.com/Keats/validator#contains)
<h3 id="required">
`#[validate(required)]` / `#[schemars(required)]`
`#[validate(required_nested)]`
</h3>
When set on an `Option<T>` field, this will create a schemas as though the field were a `T`.
Validator docs: [required](https://github.com/Keats/validator#required) / [required_nested](https://github.com/Keats/validator#required_nested)
</div>
## Other Attributes
<h3 id="schema_with">