Repository navigation
Conversation
4e0bd55 to
d6deb14
Compare
|
The CI failures here don't come from this PR. They're caused by a dependency release:
Locally, with Two ways to fix CI: bump the toolchain and |
Examples given with #[schema(examples(...))] on a Vec or other list-like type should describe the whole list and be placed on the array schema, not on its items. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vec_to_tokens took the deprecated singular `example` off the features for the array itself, but left `examples` in the features passed to the item schema. As a result #[schema(examples(...))] on a Vec, LinkedList, set, SmallVec, slice or array ended up on `items`. Pop Feature::Examples together with the other array-level features and emit it on the ArrayBuilder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
map_to_tokens popped the singular `example` but passed `examples` on to both the propertyNames and additionalProperties child schemas. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OpenAPI 3.1 Parameter Object has an `examples` map of named Example objects next to the single `example`. Add Parameter::examples and ParameterBuilder::examples_from_iter mirroring Content. Parameter is #[non_exhaustive], so the new field is not a breaking change. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Cover container, field, variant, newtype and generic schemas, request body and response content, ToResponse/IntoResponses derives, and IntoParams / path tuple parameters. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add `examples(from = <expr>)` to #[schema(...)] where <expr> is any IntoIterator. Each item is converted with Into::into to the type the examples describe and serialized with serde_json, so an example of the wrong type fails to compile at the attribute. The type is `Self` for container and variant examples, and the field type, or `value_type` when given, for field examples. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…content Media type `examples` is a map of named examples, so for request_body, responses and the ToResponse / IntoResponses derives each item of `examples(from = <expr>)` is a `(name, value)` tuple where name is Into<String> and value is converted with Into::into to the body type. A `[T]` body takes Vec<T> examples. Content without an explicit body type gives a compile error. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OpenAPI 3.1 parameters have an `examples` map of named examples. Accept
`examples(...)` on #[param(...)], IntoParams fields and params tuples in
#[utoipa::path] in the same forms as request and response content:
`examples(("name" = (value = json!(...))), ...)` and
`examples(from = <expr>)` where each item is a `(name, value)` tuple and
value is converted with Into::into to the parameter type, or its
`value_type` when given.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add a "Typed examples" section to the ToSchema docs and document the `from = ...` form for request and response content, ToResponse, IntoResponses, IntoParams and path parameters. Add compile_fail doctests for examples of the wrong type and for typed examples without a body type. Also complete two truncated `examples(...)` bullets in the enum docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
d6deb14 to
f474796
Compare
|
Rebased onto current master (c7fd8ad, which includes the zip 9.0 bump and the swagger-ui release version update). There were no conflicts and the code is unchanged. This PR still builds on #1638, so its first commits are the ones from that PR. The earlier CI failure on this PR came from the old rustc 1.88 toolchain not supporting actix-server 2.10, which master has since fixed. The new CI workflow is waiting for maintainer approval to run. |
Today every example is parsed by
AnyValue::parse_any, which accepts a literal,json!(...)or a function path. None of these forms check that an example matches the type it documents, and no form gives several examples from one Rust expression:examples(f)withfreturning aVecproduces one example that is an array. This PR adds one form that is checked against the type and accepted everywhere utoipa takes examples. All existing forms behave exactly as before.Related: #199 ("Check json examples for types that implement Serialize").
Schemas (
ToSchema)<expr>is anyIntoIterator. Each item becomes one entry ofexamples, in order. Each item is converted withInto::intoto:Selfon a struct, an enum or an enum variant;value_typewhen it is given. For the virtualvalue_type = Object/Value, the real field type is used.The item is then serialised with
serde_json::to_value. An example of the wrong type fails to compile, and the error points at the attribute:I chose
Into<T>over requiring exactlyTso that&stritems work forStringfields andVecitems work forOption<Vec<_>>fields. The cost is that integer literals do not infer the target type (for au64, write1u64). This is documented.Request body, responses,
ToResponse,IntoResponsesMedia type
examplesis a name → Example map, so here each item is a(name, value)tuple, wherename: Into<String>andvalue: Into<Body>:The body type comes from
content = …/body = …([T]takesVec<T>items). ForToResponseandIntoResponses, it is the derived type. When there is no explicit body type, the macro gives a compile error that asks for one. Names are required rather than generated automatically: this is explicit, it matches the existing named form, and it avoids ambiguity when the body type is itself a tuple.Parameters
OpenAPI 3.1 Parameter Objects have an
examplesmap, bututoipa::openapi::path::Parameteronly hadexample. This PR adds:Parameter::examples: BTreeMap<String, RefOr<Example>>andParameterBuilder::examples_from_iterinutoipa.Parameteris#[non_exhaustive], so this is not a breaking change.examples(...)on#[param(...)](IntoParams) and onparams((...))tuples in#[utoipa::path]. It accepts both the existing named form("name" = (value = json!(..)))andfrom = [(name, value)], with values converted to the field or parameter type (orvalue_type).Implementation
ExamplesFrom(inutoipa-gen/src/lib.rs, next toAnyValue) is the single parser forfrom = <expr>. It generates both the value form and the named form, usingquote_spanned!at the expression's span.attributes::Examplesis now an enum with two variants: the existing list, orfromplus the target type. Field and IntoParams code fills in the type; containers default toSelf.path::example::Examples(the list of namedExamples, orfrom) replacesPunctuated<Example, Comma>inMediaTypeAttr, in response derives, and in the newParamExamplesfeature.Parameter::examples. The generated code uses onlycore/std,utoipa::gen::serde_jsonandExampleBuilder.failed to serialize example from examples(from = ...), and the panic location is the attribute.PartialSchema::schema()is infallible, and today'sjson!(f())also unwraps inside serde_json.Tests
schema_derive_test.rs: a unit enum container, a newtype overVec(examples go on the array), fields covering&str→String,Vec,Option<Vec<_>>,HashMapandvalue_type, mixed enum variants, and a generic struct usingSelf.request_body_derive_test.rs:content = Foo, plus content groups with[Foo]andinline(Foo).path_response_derive_test.rs,response_derive_test.rs: a response body,ToResponseandIntoResponses.path_derive.rs: IntoParams fields (fromand the named form) andparamstuples.utoipaunit test forParameterBuilder::examples_from_iter.compile_faildoctests (the repo does not use trybuild): a wrong item type on a field, a wrong item type on an enum, andfromwithout a body type.Not included
example = from(...). The singularexampleis deprecated in favour ofexamples.params(...)cannot usefromyet. They get a compile error asking for an explicit type.🤖 Generated with Claude Code