tamasfe/aide

How to document Parameters?

itsbalamurali opened this issue · 7 comments

itsbalamurali commented

Hi! Do you have any example on how to document Path and Query parameters?

Wicpar commented

Use thePath<struct> extractor like you would in axum, but you need to use a struct that implements JsonSchema and document the fields accordingly

  • 👍1
  • 🚀1
v-morlock commented

Could you explain what you mean by "document the fields accordingly"? I'm doing the following and the openapi document won't contain the parameter (it's in the url in curly braces but not being listed as a parameter)

Wicpar commented 
#[derive(Deserialize, JsonSchema)]
struct NewTodo {
    /// The description for the new Todo. <-- this field documentation
    description: String,
}

/// New Todo details. <-- this struct documentation
#[derive(Serialize, JsonSchema)]
struct TodoCreated {
    /// The ID of the new Todo.  <-- and this field documentation
    id: Uuid,
}

async fn create_todo(
    State(app): State<AppState>,
    Json(todo): Json<NewTodo>,
) -> impl IntoApiResponse {
    let id = Uuid::new_v4();
    app.todos.lock().unwrap().insert(
        id,
        TodoItem {
            complete: false,
            description: todo.description,
            id,
        },
    );

    (StatusCode::CREATED, Json(TodoCreated { id }))
}
v-morlock commented

Sorry, seems like i forgot the example i wanted to show. Somehow my issue from earlier is gone now, thanks anyway! However, I can't get the following to show up in the documentation, it's only working with a struct - is that something that could be possible in the future?

    Path(id): Path<u8>,
Wicpar commented

Indeed if you don't use a JsonSchema struct it is undocumented. It needs to get the doc from somewhere

v-morlock commented
tamasfe commented

The reason why it doesn't show up is that aide has no way of inferring the name of the parameter currently. The schema of the parameters is generated separately from the path, so even though the name is in the path aide does not attempt to match it with the schema.

It would be possible to assign a random name or even match parameters based on the path, it's either suboptimal or just adds more code complexity. So for now we just recommend that you use a struct for query and path params as these will contain parameter names as well as allow you to add documentation via docstrings.

  • 👍1