Paths are always assigned to a tag with their module path

[theelderbeever]

I am trying to use nesting of OpenApi doc structs because you can't register a path that isn't defined in the same module as the utoipa::path macro. However, with a nested api doc I keep getting a an extra tag header with the module location for each path. How can I get rid of that?

Additionally, why isn't it possible to register a path in a separate module?

#[derive(OpenApi)]
#[openapi(
    paths(some::other::mod::get_path), // This complains about __path_get_path not being accessible
    components(schemas(crate::api::v1::usage::schemas::Params))
)]
pub struct ApiDoc;

[juhaku]

I am trying to use nesting of OpenApi doc structs because you can't register a path that isn't defined in the same module as the utoipa::path macro. However, with a nested api doc I keep getting a an extra tag header with the module location for each path. How can I get rid of that?

Not sure do I understand the problem, but there is a way to provide custom tag for the operation with the following.

 #[utoipa::path(
   tag = ...
 )]

Then the operations that has the same tag will be grouped together. Depending on which version of utoipa you are currently using you either have the tag = ... and tags = ... attribute as seen in the docs https://docs.rs/utoipa/5.0.0-alpha.1/utoipa/attr.path.html#path-attributes. The utoipa 4.x.x does not have the tags = ... attribute. Tags attribute should allow adding additional tags, while the tag should override the default tag which is the path to the operation function by default.

Additionally, why isn't it possible to register a path in a separate module?

Actually it is but the path must be pub as the #[utoipa::path] attribute macro generates a struct that implements Path trait but the visibility will be the same as the function is. So with this the some::other::mod::get_path should be public function.

#[derive(OpenApi)]
#[openapi(
    paths(some::other::mod::get_path), // This complains about __path_get_path not being accessible
    components(schemas(crate::api::v1::usage::schemas::Params))
)]
pub struct ApiDoc;

[theelderbeever]

@juhaku I am pointing at your main/5.x.x.

The tag field does not override the default tag. It just make an additional tag. Thats the issue I was trying to get across poorly.

 #[utoipa::path(
   tag = ...
 )]

The following does not appear to be true. Everything I have is pub, the path handler and all the mods above it.

the #[utoipa::path] attribute macro generates a struct that implements Path trait but the visibility will be the same as the function is.

[theelderbeever]

In the next few days I can link an example using your todo app to demonstrate what I am talking about.

[daniel-mader]

Is there any news on this? I'm having the same issue (default module path tags I cannot get rid of, no matter if I'm using tag or tags).

[juhaku]

@theelderbeever Okay, thanks for pointing out. I assume there is a bug in the tags processing it should be investigated that what's the deal in the code.

[juhaku]

The following does not appear to be true. Everything I have is pub, the path handler and all the mods above it.

the #[utoipa::path] attribute macro generates a struct that implements Path trait but the visibility will be the same as the function is.

Yes it seems that the doc has not been updated since the behavior has been changed probably long ago. However it will generate allways pub struct regardless whether the handler fn itself is pub or not.

The following code is possible to nest paths from sub module paths without exposing the module path to the derive macro.

mod test_path {
    #[allow(dead_code)]
    #[utoipa::path(get, path = "/test")]
    #[allow(unused)]
    pub fn test_path() -> &'static str {
        ""
    }
}

mod test_nest {
    #[derive(utoipa::OpenApi)]
    #[openapi(paths(test_path_nested))]
    pub struct NestApi;

    #[allow(dead_code)]
    #[utoipa::path(get, path = "/test")]
    #[allow(unused)]
    fn test_path_nested() -> &'static str {
        ""
    }
}

use test_nest::NestApi;
use test_path::__path_test_path;
#[derive(utoipa::OpenApi)]
#[openapi(
    paths(test_path),
    nest(
        (path = "/api/nest", api = NestApi)
    )
)]
struct ApiDoc;