support for "examples" annotations

[mash-graz]

is there any support for examples annotation entries available in schemars and how to realize this kind of augmentation with serde resp. docstrings or anything similar?

unfortunately i couldn't find anything about this kind of non-validation oriented auxiliary annotations in the present schemars documentation and examples.

[GREsau]

This isn't yet supported, but this is a sensible enhancement that I'll definitely consider implementing.

This would probably work by creating a function that returns the example value and setting it in an attribute, the same way serde's default attribute works, for example:

#[derive(Serialize, Deserialize, JsonSchema)]
#[schemars(example = "example_person")]
struct Person {
    first_name: String,
    last_name: String,
}

fn example_person() -> Person {
    Person {
        first_name: "John".to_owned(),
        last_name: "Doe".to_owned(),
    }
}

[mash-graz]

thanks for your encouraging answer!

This would probably work by creating a function that returns the example value and setting it in an attribute, the same way serde's default attribute works, ...

yes i already have to use this mechanism in my actual code to set some boolean an enum defaults, but i have to say, it's a rather inconvenient and unwieldy solution. using some kind of markup in the docstring would IMHO be more comfortable and suitable in this particular case, but at the end i would just appreciate any clever support resp. real world implementation of this feature.

[GREsau]

This is implemented in schemars v0.7.6, which is now published to crates.io

[mash-graz]

@GREsau
thank's for supporting this feature!
it's incredible useful for an application, which i started to write recently utilizing your library:
https://gitlab.com/mash-graz/covtc

[ralpha]

Did not spot this feature at first. But nice to see it come 😃
I wanted to implement this to test it out but seems that is does not work with openapi spec.
The OpenAPI spec has some fields with examples but components -> schemas -> {name} -> examples is not one of them as I can see.

• There is components -> examples -> {name} -> ...
• There is components -> schemas -> {name} -> example
• There is paths -> /{path} -> {get} -> responses -> {HTTP status code} -> content -> {media type} -> example
• And probably others.

I am far from an expert on openapi so could be wrong. I find this helpful to see the structure: http://openapi-map.apihandyman.io/

Edit: Just found this: GREsau/okapi#11 (comment) That confirms it, maybe it should be handled there.