Extractor documentation

[blinsay]

I've been using aide on an API with some String and Uuid path parameters and just figured out through trial-and-error that they need to be wrapped in a struct type to have openapi parameters correctly generated for them. Now that I've discovered it, this makes some amount of sense, but I'd love to have it documented explicitly somewhere (Apologies if it already is, I couldn't find it).

I haven't finished going through my API yet so I'm not sure if this true of query parameters as well.

What I did

This happily compiled, but generated me an openapi route with no parameters:

async fn get_widget(
    State(ctx): State<ApiContext>,
    Path(widget_id): Path<Uuid>,
) -> Result<Json<Widget>> {
...
}

I had to switch to something like this to get documentation generated:

#[derive(Deserialize, JsonSchema)]
struct WidgetId {
    widget_id: Uuid,
}

async fn get_network_group(
    State(ctx): State<ApiContext>,
    Path(ids): Path<WidgetId>,
) -> Result<Json<Widget>> {
...
}

An easy repro

This is really easy to reproduce with the example-axum example. If you switch to a plain Uuid the path parameter disappears!

diff --git a/examples/example-axum/src/todos/routes.rs b/examples/example-axum/src/todos/routes.rs
index 15edab4..6115fc8 100644
--- a/examples/example-axum/src/todos/routes.rs
+++ b/examples/example-axum/src/todos/routes.rs
@@ -95,9 +95,9 @@ struct SelectTodo {

 async fn get_todo(
     State(app): State<AppState>,
-    Path(todo): Path<SelectTodo>,
+    Path(id): Path<Uuid>,
 ) -> impl IntoApiResponse {
-    if let Some(todo) = app.todos.lock().unwrap().get(&todo.id) {
+    if let Some(todo) = app.todos.lock().unwrap().get(&id) {
         Json(todo.clone()).into_response()
     } else {
         StatusCode::NOT_FOUND.into_response()