如何在Rust poem-openapi中将API端点拆分到多文件实现？

问题原因 #

直接在多个impl Endpoints块上添加#[OpenApi]会触发OpenApi trait重复实现的错误；去掉该宏后，#[oai]属性无法被识别——因为它是由#[OpenApi]宏注入的作用域属性，仅在该宏修饰的impl块内有效。

解决方案 #

将不同业务组的端点拆分到独立的API结构体中，每个结构体单独使用#[OpenApi]宏标记，最后在主函数中合并多个API服务。

修正后的main.rs

use poem::{listener::TcpListener, Route};
use poem_openapi::{OpenApi, OpenApiService};

// 导入各个独立的API模块
mod some_endpoints;
mod more_endpoints;

use some_endpoints::SomeEndpoints;
use more_endpoints::MoreEndpoints;

#[tokio::main]
async fn main() -> Result<(), std::io::Error> {
    // 创建各个API服务实例
    let some_api = OpenApiService::new(SomeEndpoints, "Some Endpoints", "1.0");
    let more_api = OpenApiService::new(MoreEndpoints, "More Endpoints", "1.0");

    // 合并多个API服务
    let combined_api = some_api.merge(more_api);

    let docs = combined_api.swagger_ui();
    let app = Route::new()
        .nest("/api", combined_api)
        .nest("/", docs);
    
    poem::Server::new(TcpListener::bind("127.0.0.1:3000"))
        .run(app)
        .await
}

修正后的some_endpoints.rs

use poem_openapi::{OpenApi, payload::PlainText};

// 独立的API结构体，对应一组相关端点
pub struct SomeEndpoints;

#[OpenApi]
impl SomeEndpoints {
    /// Some dummy endpoints
    #[oai(path = "/dummy", method = "get")]
    async fn dummy(&self) -> PlainText<&'static str> {
        PlainText("Hello, world!")
    }
}

修正后的more_endpoints.rs

use poem_openapi::{OpenApi, payload::PlainText};

pub struct MoreEndpoints;

#[OpenApi]
impl MoreEndpoints {
    /// Another dummy endpoint
    #[oai(path = "/another", method = "get")]
    async fn another(&self) -> PlainText<&'static str> {
        PlainText("Another endpoint response!")
    }
}

Cargo.toml保持不变

# ...
[dependencies]
poem = "1.3.55"
poem-openapi = { version = "2.0.26", features = ["swagger-ui"] }
tokio = { version = "1", features = ["full"] }

说明 #

• 每个端点组对应独立结构体，彻底避免了OpenApi trait重复实现的冲突。
• 通过OpenApiService::merge方法可合并任意数量的API服务，最终生成统一的路由和API文档。
• 该方案既满足代码模块化拆分需求，又完全符合Poem-OpenApi的宏设计规则。

内容的提问来源于stack exchange，提问作者nikolaj