Rust使用paperclip实现REST API如何让响应模型在Swagger UI展示

你的问题核心是使用了actix原生的HttpResponse构建方法，丢失了响应体的类型信息，导致paperclip无法识别模型。按以下步骤修改即可：

1. 补全依赖类型的派生属性 #

首先确认你定义的Customer结构体也派生了Apiv2Schema和Serialize，否则嵌套的模型无法被正确识别：

#[derive(Serialize, Apiv2Schema)]
struct Customer {
    // 你的字段定义
}

2. 修改响应返回方式 #

有两种可选方式替换你当前的HttpResponse构建逻辑：

方式一：直接返回Json包装的响应体（更简洁） #

直接用paperclip提供的web::Json包装响应体，无需手动构建HttpResponse，paperclip会自动完成序列化和类型识别：

/// Get all customers
#[api_v2_operation]
pub async fn get_customers(_db_pool: web::Data<Pool>) -> Result<web::Json<CustomerResponse>, Error> {
    let customers = load_customers()?;
    Ok(web::Json(CustomerResponse {
        customer: customers,
    }))
}

方式二：使用paperclip扩展的ResponseBuilder方法 #

如果你需要自定义响应头、状态码等配置，可以导入paperclip的扩展trait，使用扩展的json方法构建响应：
首先导入扩展：

use paperclip::actix::ResponseBuilderExt;

然后修改响应构建逻辑：

/// Get all customers
#[api_v2_operation]
pub async fn get_customers(_db_pool: web::Data<Pool>) -> Result<HttpResponse, Error> {
    let customers = load_customers()?;
    Ok(HttpResponse::Ok()
        // 这里可以加自定义头、状态码等配置
        .json(CustomerResponse {
            customer: customers,
        })
    )
}

3. 确认应用初始化开启了paperclip扫描 #

确保你在应用初始化时调用了wrap_api()方法开启paperclip的API信息扫描，否则也无法生成正确的规范：

use paperclip::actix::AppExt;
use actix_web::{HttpServer, App};

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .wrap_api() // 必须添加该方法启用paperclip能力
            .service(control_routes())
            .with_json_spec_at("/api/spec/v2") // 配置swagger规范json的访问路径
            .with_swagger_ui_at("/api/docs") // 配置swagger ui的访问路径
            .build()
    })
    .bind(("127.0.0.1", 8080))?
    .run()
    .await
}

修改完成后重新编译运行，Swagger UI就会正确展示CustomerResponse的模型结构和示例了。

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