BUG: poem_openapi::param::Path is buggy on strings

[izelnakri]

Expected Behavior

use poem::{
    listener::TcpListener,
    web::{Path},
    Route, Server,
    handler
};

use poem_openapi::{
    payload::PlainText,
    param::Path as ApiPath, 
    OpenApi, OpenApiService, 
};

#[handler]
async fn get_user(
    Path(username): Path<String>,
) -> PlainText<String> {
    PlainText("This works and can get the input".to_string())
}

struct Api {}

#[OpenApi]
impl Api {
    #[oai(method = "get", path = "/:username")]
    async fn fetch_user(
        &self,
        ApiPath(username): ApiPath<String>,
    ) -> PlainText<String> {
        // This gives: failed to parse path `username`: Type "string" expects an input value.
        PlainText("This doesnt work and cant extract the input".to_string())
    }

    #[oai(path = "/", method = "get")]
    async fn index(&self) -> PlainText<&'static str> {
        PlainText("Hello World")
    }
}

#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
    let api_service = OpenApiService::new(
        Api {},
        "My API",
        env!("CARGO_PKG_VERSION"),
    )
    .server(format!("http://localhost:1234/api"))
    .description("A simple API")
    .summary("Information API");

    let openapi_ui = api_service.swagger_ui();
    let app = Route::new()
        .at("/:username", get_user) 
        .nest("/api", api_service)
        .nest("/openapi", openapi_ui);

    println!("Starting server on port 1234...");
    Server::new(TcpListener::bind(format!("0.0.0.0:1234")))
        .run(app)
        .await?;

    Ok(())
}

Actual Behavior

GET http://localhost:1234/api/izelnakri:

failed to parse path username: Type "string" expects an input value.

GET http://localhost:1234/izelnakri:

This one works

Steps to Reproduce the Problem

1. Run the code yourself

Specifications

• Version: LATEST = poem v3.1.10, poem-openapi v5.1.14
• Platform: Linux omnibook 6.14.5 add README #1-NixOS SMP PREEMPT_DYNAMIC Fri May 2 06:02:16 UTC 2025 x86_64 GNU/Linux

We need better tests for all the types in open

[unix4lyf]

Observations: using param::Path directly from poem_openapi works.

use poem::{Route, Server, handler, listener::TcpListener, web::Path as WebPath};

use poem_openapi::{OpenApi, OpenApiService, param::Path, payload::PlainText};

#[handler]
async fn get_user(WebPath(username): WebPath<String>) -> PlainText<String> {
    println!("Direct handler: {username}");
    PlainText("This works and can get the input".to_string())
}

struct Api {}

#[OpenApi]
impl Api {
    #[oai(method = "get", path = "/:username")]
    async fn fetch_user(&self, Path(username): Path<String>) -> PlainText<String> {
        println!("From OpenAPI: {username}");
        PlainText(format!("This works! {username}"))
    }

    #[oai(path = "/", method = "get")]
    async fn index(&self) -> PlainText<&'static str> {
        PlainText("Hello World")
    }
}

#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
    let api_service = OpenApiService::new(Api {}, "My API", env!("CARGO_PKG_VERSION"))
        .server(format!("http://localhost:1234/api"))
        .description("A simple API")
        .summary("Information API");

    let openapi_ui = api_service.swagger_ui();
    let app = Route::new()
        .at("/:username", get_user)
        .nest("/api", api_service)
        .nest("/openapi", openapi_ui);

    println!("Starting server on port 1234...");
    Server::new(TcpListener::bind(format!("0.0.0.0:1234")))
        .run(app)
        .await?;

    Ok(())
}

Observation: When aliasing import of poem_openapi::param::Path to APIPath, it breaks. Somehow, the alias is not being properly handled.

    #[oai(method = "get", path = "/:username")]
    async fn fetch_user(&self, APIPath(username): APIPath<String>) -> PlainText<String> {
        // This gives: failed to parse path `username`: Type "string" expects an input value.
        println!("From OpenAPI: {username}");
        PlainText(format!("This breaks! {username}"))
    }

[unix4lyf]

@attila-lin @sunli829

[gwik]

I believe commit 6ea16fd is responsible.

Basically it renames the path variable to deterministic names base on order of appearance only when the type of the extractor matches "Path" e.g.:

foo/:foo/bar/:bar

Becomes:

foo/:param0/bar/:param1

But there are many cases where this doesn't work:

• Path aliases are not matched by the proc macro because it checks the argument type to be the string Path.

• Custom extractors (and aliases) that rely on some variable name convention no longer work if a Path extractor is also present. I agree that this may not be a great idea in the first place, but it's very surprising that the variable name is changed.

• If not all the path params are used (and probably if bound in the handler method arguments in a different order).

#[oai(method = "get", path = "/foo/:custom/bar/:bar")]
fn handler(custom: MyCustomExtractor(foo), bar: Path<String>) {
 // bar will be set to the value of :custom because it will be remapped to 
 // `param0` and that the first "Path" that the macro sees.
 
 // MyCustomExtractor that rely on `:custom` no longer works.
}

The original purpose for this commit is to allow for routes with common prefix but different variables names to function.

GET "/foo/:aaa"
POST "/foo/:bbb"

I dug a bit and I think the only way to implement this without resorting to hacks like checking for Path in the proc macro is to make the router method aware or have some sort of discriminant mechanism. So when traversing the route radix tree it can continue with the next candidate route when the method doesn't match.

@robko23 clearly stated that the implementation is a bit janky in the commit message.
My opinion, with all due respect, is this patch should be reverted and the release yanked until we find a better solution.

[gwik]

If downgrading is inadequate for you, you can add this to your Cargo.toml.

It's simply a revert of the commit on top of the last release.

[patch.crates-io]
poem = { git = "https://github.com/gwik/poem.git", rev = "c42c40550ed5fd47b3f42854aed28b6b46871f15", version = "3.1.10" }
poem-openapi = { git = "https://github.com/gwik/poem.git", rev = "c42c40550ed5fd47b3f42854aed28b6b46871f15", version = "5.1.14" }
poem-grpc = { git = "https://github.com/gwik/poem.git", rev = "c42c40550ed5fd47b3f42854aed28b6b46871f15", version = "0.5.5" }
poem-grpc-build = { git = "https://github.com/gwik/poem.git", rev = "c42c40550ed5fd47b3f42854aed28b6b46871f15", version = "0.5.5" }

[robko23]

@gwik you're right, there is hardcoded if statement that compares whether the function param type is named Path.
It is related to issue #429 and #948 and this was the first solution that came up to my mind and that passed all the tests.
I don't mind reverting the commit, as I said, it is janky and I stand by that opinion. However, keep in mind that this would re-introduce the bug. I think we should come up with some better solution, because it seems that this bug keep being fixed and then re-introduced.
I will be more than happy to help with the implementation, but I wont have much time till the next weekend because of my finals

[Nordalf]

Bumping this one, since I'm having a similar issue with parsing an UUID (user_id) using version poem:3.1.12 and poem_openapi:5.1.16.

The issue:

When adding a prefix_path to the OpenApi proc_macro, then I'm thrown the same error: failed to parse path param0: failed to parse "string_uuid": invalid character: expected an optional prefix of urn:uuid: followed by [0-9a-fA-F-], found m at 1.

E.g.

File1.rs
#[OpenApi(prefix_path = "/v1/users/:user_id/route1")]

File2.rs
#[OpenApi(prefix_path = "/v1/users/:user_id/route2")]

I'm using the poem_openapi::param::Path import.

If I move the param out of my prefix and into my endpoint path, then it works fine:

    #[OpenApi(prefix_path = "/v1/users")]
    #[oai(
        path = "/:user_id/route1/:other_param",
        method = "get",
        tag = "ApiTags::Table"
    )]

Have anyone come across a similar issue?