How to add multipart to swagger? Nested routers error

[Kimishu]

Greetings. Firstly, I want to apologize for hasty created topic in issues section. Here it is, it can be deleted. That's my first time in discussions/issues.

Currently I have two problems and I'll try to describe it as full as I can.

1. How to add multipart to the documentation?
   Before I used rocket and okapi for file uploading, but as hasty person, I missed well-written utoipa and axum. I need to add upload opportunity to send files through swagger.
   After some tries I got something like below. I want to upload json-body + file. And I want to upload them from swagger. Is it possible?

(Tried to use struct here, but I think there is solution that uses axum::extract::Multipart, cause it's doesnt allow me to upload concrete file from swagger)

#[derive(ToSchema)]
struct TestForm {
    #[schema(content_media_type = "application/octet-stream")]
    file_bytes: Vec<u8>
}

#[utoipa::path(
    tag = "USER",
    post,
    path = "/create",
    responses(
        (status = 200, description = "Done")
    ),
    request_body(content = TestForm, content_type = "multipart/form-data")
)]
#[debug_handler]
async fn user_post(data: TestForm) -> impl IntoResponse {
    return StatusCode::OK
}

and now I have this:

#[utoipa::path(
    tag = USER,
    path = "/create",
    post,
    responses(
        (status = 200, description = "User created successfully!"),
        (status = 400, description = "Unsupported entity"),
        (status = 401, description = "Server token doesn't provided!")
    ),
    security(
        ("server_token" = [])
    ),
    //request_body(content="multipart/form-data", content-type = Multipart?)
)]
async fn post_user(db: State<Arc<Pool>>, mut data: Multipart) -> impl IntoResponse {
...
}

2. Nested routers error.
   Yep, this is the error. And I really don't know where I should ask about this. For example, I have a service that does handling functions. And I want to logically split all routes to groups. Like, user group would perform only user tasks and can be accesable through /user/... route. Code below shows it.
   But here I got an error, that says I can't put two POST requests at the same path. But paths are different. Yes, they have one common path /user/ but they have different paths like /post_1 and /post_2 as example. And I don't know how to solve this.

//main.rs
let (router, api) = (...).nest("/user", user_routes)
//user_handler.rs
pub fn user_routes() -> OpenApiRouter {
    OpenApiRouter::new().routes(routes!(
        user_post_1, //errors
        user_post_2 //errors
    ))
}

Thanks in advance!

[Kimishu]

So, after a week of mind pain, I have found out this:

...
OpenApiRouter::new().routes(routes!(get_first)).routes(routes!(get_second))...
...

Idk why, but I also created a topic on stackoverflow. There u can see raw axum example where nesting routes.. Working. Idk why, but it seems like and issue that utoipa can't see my paths attributes differences and started yelling at that after compilation.. So, I hope this will be fixed, because it's not cool. (Like, in other frameworks this works fine, and here too, but.. I want to make documentation.. )
And the problem with multipart still exists.
If someone has another suggestion - you are welcome!

[juhaku]

I just added couple of examples on how to define multipart form uploads. https://github.com/juhaku/utoipa/tree/master/examples/axum-multipart https://github.com/juhaku/utoipa/tree/master/examples/actix-web-multipart

For what comes to 2. problem, it is same issue as here: #1183 (comment). In short the routes! macro call is single axum MethodRouter which allows only single handler per http method.

Hope these will get you forward.

[juhaku]

Unfortunately my example in docs with Vec<u8> as you have used above there as well is not really working as expected. The latest version of OpenAPI spec has corrected their examples I originally based my examples of.

[juhaku]

For what comes to 2. problem, it is same issue as here: #1183 (comment). In short the routes! macro call is single axum MethodRouter which allows only single handler per http method.

Probably the utoipa's implementation could be smart enough to split the given handlers to multiple axum MethodRouter implementations if it finds multiple http methods that are same. While it would be a nice convenience it certainly will add to the complexity of a macro which is not necessarily an easy task. Anyhow the error itself comes from axum side.

[Kimishu]

I just added couple of examples on how to define multipart form uploads. https://github.com/juhaku/utoipa/tree/master/examples/axum-multipart https://github.com/juhaku/utoipa/tree/master/examples/actix-web-multipart

For what comes to 2. problem, it is same issue as here: #1183 (comment). In short the routes! macro call is single axum MethodRouter which allows only single handler per http method.

Hope these will get you forward.

Yeah! That's exactly what I want. Thank u a lot for utoipa, for ur feedback, u are the best!
In case of second problem, I'll write to axum's discussion again (I already did that here). Anyway, I've found something like soultion and.. For now I just will use multiple routes!() macros 😁

...
OpenApiRouter::new().routes(routes!(get_first)).routes(routes!(get_second))...
...

And the last one, I saw another problem when working with params. (Idk should I create a different discussion for that or no) In default axum we can use something like this:

async fn params_vec(
    Path(params): Path<Vec<(String, String)>>,
) {
    // ...
}

But it doesn't work with utoipa and I should write like this:

#[utoipa::path(
    tag = UPDATES,
    path = "/download/{version}",
    get,
    params(
        ("version" = String, description = "Version that will be downloaded")
    )
)]
async fn test(Path(params) : Path<Vec<(String,String)>>) -> impl IntoResponse {}

Once again, thank you very much. I appreciate your help and understand what kind of work it is. You are a great guy, I wish you only success! 😉

[juhaku]

For now I just will use multiple routes!() macros 😁

Yeah, that is the way to do it for now. It is completely valid to call routes! multiple times. It would be effectively same as calling route(..) method on axum router multiple times.

How should the vec path params work?

async fn params_vec(
   Path(params): Path<Vec<(String, String)>>,
) {
   // ...
}

The utoipa expects the path to match to actual params. E.g. the example below will work.

#[utoipa::path(
    tag = UPDATES,
    path = "/download/{version}",
    get,
    params(
        ("version" = String, description = "Version that will be downloaded")
    )
)]
async fn test(Path(version) : Path<String>) -> impl IntoResponse {}

// .. multiple params
#[utoipa::path(
    tag = UPDATES,
    path = "/download/{version}/foo/{another}",
    get,
    params(
        ("version" = String, description = "Version that will be downloaded"),
        ("another", description = "Another param"), // you may omit the type as it comes from the handler type.
    )
)]
async fn test(Path((version, another)) : Path<(String, String)>) -> impl IntoResponse {}