Skip to content
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

Automatic type recognition for path operation handlers #591

Open
7 of 10 tasks
juhaku opened this issue Apr 18, 2023 · 6 comments · Fixed by #582, #589, #666, #668 or #670
Open
7 of 10 tasks

Automatic type recognition for path operation handlers #591

juhaku opened this issue Apr 18, 2023 · 6 comments · Fixed by #582, #589, #666, #668 or #670
Labels
enhancement New feature or request

Comments

@juhaku
Copy link
Owner

juhaku commented Apr 18, 2023

Description

To streamline further the utoipa library and to provide deeper integeration for frameworks like actix_web, axum, and rocket it would be great to be able to automatically recognize necessary types from operation handler and add them to the path schema of OpenAPI doc generated with utoipa. This will provide more automation and saves the keystrokes the user is ought to take to define #[utoipa::path(...)] macro content manually.

For example, from following handler function we would need to be able to recognize path, query, body and response. These recognized values, if successful, should be added automatically to the generated OpenAPI spec.

#[utoipa::path]
async fn post_item(path: Path<PathParams>, query: Query<QueryParams>, item: Json<ItemBody>) -> Response {
    Response::Success(Item { value: "super".to_string() })
}

This functionality will enforce users to be more strict on what is being returned from the handler functions and what are the args given to the handler functions. Benefit of this is the users are able to declare the OpenAPI spec mostly via code and get compile errors directly to the code of invalid spec.

Tasks

  • Implement general response body recognition - All responses need to implement IntoResponses trait.
  • Implement response body recognition for actix_web
  • Implement response body recognition for axum
  • Implement response body recognition for rocket
  • Implement request body recognition for actix_web
  • Implement request body recognition for axum
  • Implement request body recognition for rocket
  • Enhance current path and query parameter support in actix_web to support auto recognition
  • Enhance current path and query parameter support in axum to support auto recognition
  • Enhance current path and query parameter support in rocket to support auto recognition
@juhaku juhaku added the enhancement New feature or request label Apr 18, 2023
@TheDan64
Copy link

I think related; it was really surprising (in axum) that Path<(X, Y)> would auto generate the path params but Path<X> does not

@juhaku
Copy link
Owner Author

juhaku commented Apr 28, 2023

Yeah, I can take a look at this at the same time.

@juhaku
Copy link
Owner Author

juhaku commented Jun 12, 2023

Any ideas are welcome to this one #649. Currently not sure at the moment how to proceed with the implementation. The biggest issue is that if I have a handler such as seen below, I can only resolve responses for Result type based on assumtions without the possibility to realiably change / override or ignore them later on. This practically becomes quite limiting if we assume that the responses from the given handler were only 200 for success and default for any possible error. Sure we can add more responses with the responses(...) attribute in utoipa::path macro, but we cannot map them reliably with the auto-resolved ones.

#[utoipa::path]
#[get("/item")]
async fn get_item() -> Result<Json<Item<'static>>, Error> {
    Ok(Json(Item { value: "super" }))
}

@juhaku
Copy link
Owner Author

juhaku commented Jul 9, 2023

I think related; it was really surprising (in axum) that Path<(X, Y)> would auto generate the path params but Path<X> does not

@TheDan64 This PR #668 should fix the issue in the path parameters.

@TheDan64
Copy link

@juhaku thanks! is this in 3.4.3? I seem to be having the same issue still

@juhaku
Copy link
Owner Author

juhaku commented Aug 3, 2023

@juhaku thanks! is this in 3.4.3? I seem to be having the same issue still

Here is some more examples how the path parameter can be recognized: 7cc90b1.

It is not fully automatic because the original behavior was reverted as it caused unwanted issues for many users. There is some work to do for make this implementation better but for what comes to the axum path parameters the name of the handler argument must match to the path arguments otherwise they will not be added.

    // `id` must match to the path argument name.
    async fn get_item(id: Path<u32>) {}
    
    // `id and `id2` must match to the path argument name.
    async fn get_item(Path((id, id2)): Path<(u32, u32)>) {}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment