QueryParam generated documentation usage

[hadrien-toma]

Hello here :wave::blush:! First: thank you very much for the awesome work done in this repo :pray: :heart_eyes: !

I try to fill the generated documentation with "examples", especially for a QueryParam.

Here are the changes I made in examples/example-axum/src/todos/routes.rs in order to do some tests, focusing on the /todo/{id}/complete use case (I also imported Query from axum::extract):

• Image:
• Code:

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
pub struct Int32DefaultedTo20(pub u32);

impl Default for Int32DefaultedTo20 {
	fn default() -> Self {
		Int32DefaultedTo20(20)
	}
}
impl Clone for Int32DefaultedTo20 {
	fn clone(&self) -> Self {
		Int32DefaultedTo20(self.0.clone())
	}
}

fn index_serde_defaulted_with_value_fn() -> u32 {
	22
}

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
pub struct StringDefaultedToHello(pub String);

impl Default for StringDefaultedToHello {
	fn default() -> Self {
		StringDefaultedToHello("hello".to_string())
	}
}
impl Clone for StringDefaultedToHello {
	fn clone(&self) -> Self {
		StringDefaultedToHello(self.0.clone())
	}
}

fn text_serde_defaulted_with_value_fn() -> String {
	"text_serde_default_value".to_string()
}

#[derive(Deserialize, Debug, JsonSchema)]
pub struct CompleteTodoQuery {
	/// The index
	#[validate(range(min = 18, max = 20))]
	pub index: u32,

	/// The index_as_u32_20
	#[validate(range(min = 19, max = 21))]
	pub index_as_u32_20: Int32DefaultedTo20,

	/// The index_serde_defaulted
	#[validate(range(min = 20, max = 22))]
	#[serde(default)]
	pub index_serde_defaulted: u32,

	/// The index_serde_defaulted_with_value
	#[validate(length(min = 21, max = 23))]
	#[serde(default = "index_serde_defaulted_with_value_fn")]
	pub index_serde_defaulted_with_value: u32,

	/// The text
	#[validate(length(min = 1))]
	pub text: String,

	/// The text_as_string_hello
	#[validate(length(min = 2))]
	pub text_as_string_hello: StringDefaultedToHello,

	/// The text_serde_defaulted
	#[validate(length(min = 3))]
	#[serde(default)]
	pub text_serde_defaulted: String,

	/// The text_serde_defaulted_with_value
	#[validate(length(min = 4))]
	#[serde(default = "text_serde_defaulted_with_value_fn")]
	pub text_serde_defaulted_with_value: String,
}

async fn complete_todo(
	State(app): State<AppState>,
	Path(todo): Path<SelectTodo>,
	Query(query): Query<CompleteTodoQuery>,
) -> impl IntoApiResponse {
    println!("query: {:?}", query);
    if let Some(todo) = app.todos.lock().unwrap().get_mut(&todo.id) {
        todo.complete = true;
        StatusCode::NO_CONTENT
    } else {
        StatusCode::NOT_FOUND
    }
}

Here are the results at http://127.0.0.1:3000/docs:

• View:
• Send Request:

I noticed the following:

• text_serde_defaulted is missing
• index_serde_defaulted has 0 as value and is not visible in the curl example, whereas without serde_default it was 1 and it was visible in the curl example

What I would like is to have a way to set an example value for a query param:

• This value requires to be independent from the "required" state of the query param (they are not really "defaults" but "examples")
• This value requires be visible:
  • In the curl example of the main view (curl request ready to copy/paste with example values)
  • In the Send Request view, as the value in the cell in the "value" column related to the query param

Does anyone have some keys or tricks to achieve this need? :four_leaf_clover: :grimacing: