-
Notifications
You must be signed in to change notification settings - Fork 112
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Annotation for example values #11
Comments
I need this ! {
"code": "string",
"description": "string"
} use serde::{Deserialize, Serialize};
use schemars::JsonSchema;
#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(rename_all="camelCase")]
pub struct Version {
pub code: String,
pub description: String,
} |
@GREsau is it Rust newbie doable ? |
What syntax should be used if this is implemented? Something like: #[okapi(example = "This is the example string")] Or because this is part of schemars: #[schemars(example = "This is the example string")] Used like this: #[derive(Serialize, Deserialize, JsonSchema)]
#[serde(rename_all="camelCase")]
pub struct Version {
#[schemars(example = "1.0.0")]
pub code: String,
#[schemars(example = "First release of our crate/application.")]
pub description: String,
} I created a new issue in Schemars for this. Linked below. |
This is currently implemented in Schemars (GREsau/schemars#23), but unfortunately this doesn't work for okapi because OpenAPI 3.0 does not understand JSON Schema's "examples" keyword (see "example vs examples" here) We could fix this by adding a new |
I've now implemented the above change, so if you attach a You can try it out now in rocket-okapi v0.6.0-alpha-1 |
Thank you ! |
Ah you'll also need to update okapi to okapi |
Sorry to ask this here, but I have no idea on how to fix this for now |
What version of okapi and schemars are you referencing in your Cargo.toml? Make sure they match the dependency versions listed on https://crates.io/crates/rocket_okapi/0.6.0-alpha-1 |
Thank you for the support ! And I implemented my first example with mountains/permafrost@7d4229f And it looks very more sexy on Swagger 🚀 |
@GREsau It might be worthwhile to export okapi and schemars in rocket_okapi, so it's impossible to use incorrect versions together, and also clean up people's cargo.toml a bit. We can put schemars behind a feature flag that is on by default, since you will almost always need it. If you're open to this I can make a PR. :) |
I Just tested this out and works correct. Just for anyone in the future here is some example code: #[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
#[schemars(example = "example_item")]
pub struct Item {
pub id: i32,
pub name: Option<String>,
pub numbers: Vec<i32>,
}
fn example_item() -> Item{
Item{
id: 5,
name: Some("This is just the perfect name".to_owned()),
numbers: vec![20,21],
}
} Or you can do a function in the impl: #[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
#[schemars(example = "Self::example")]
pub struct Item {
pub id: i32,
pub name: Option<String>,
pub numbers: Vec<i32>,
}
impl Item{
pub fn new() -> Self{
Self::default()
}
// This function does not have to be public (if it is in the same module).
pub fn example() -> Self{
Self{
id: 5,
name: Some("This is just the perfect name".to_owned()),
numbers: vec![20,21],
}
}
} @GREsau Just one thing I noted is that when you do this the order of the fields is not order correctly with the |
When implementing (although not finished with it yet) I had to add a trait pub trait SchemaExample{
fn example() -> Self;
} Because I have some generics with nested objects. Example: #[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
#[schemars(example = "Self::example")]
pub struct ApiItem<D> where
D: ApiObject + Serialize + SchemaExample{
/// A unique string identifier for this type.
#[serde(rename = "_type")]
pub type_: String,
/// Links the various related items.
#[serde(rename = "_links")]
pub links: ApiItemLinks,
/// The included data item.
#[serde(flatten)]
pub data: D,
/// Server base url.
/// Not included in response.
#[serde(skip)]
pub base_url: String,
}
impl<D> SchemaExample for ApiItem<D> where D: SchemaExample + Serialize + ApiObject{
fn example() -> Self{
Self{
type_: "example".to_owned(),
links: ApiItemLinks::example(),
data: D::example(),
base_url: "".to_owned(),
}
}
} Otherwise I could not get the Also note that you can then use This trait could also be implemented in Edit: |
Ah, I think you'll need to enable the |
That was exactly what the problem was! serde_json = { version = "1.0", features = ["preserve_order"] }
# Also for schemars
schemars = { version = "0.8.0-alpha-4", features = ["preserve_order"] } |
Is there a reason why this isn't closed? |
This is already implemented and merged, closing issue. |
I was thinking about an annotation on the data type maybe.
The text was updated successfully, but these errors were encountered: