Rust Web框架Actix插件paperclip-actix使用指南

完整示例代码

下面是一个完整的paperclip-actix使用示例，集成了前面提到的各种功能：

use actix_web::{web, App, HttpResponse, HttpServer, Result};
use paperclip::actix::{
    api_v2_operation, 
    Apiv2Schema,
    OpenApiExt
};
use serde::{Serialize, Deserialize};

// 定义宠物数据结构
#[derive(Debug, Serialize, Deserialize, Apiv2Schema)]
struct Pet {
    id: u64,
    name: String,
    tag: Option<String>,
}

// 定义错误响应结构
#[derive(Debug, Serialize, Apiv2Schema)]
struct ErrorResponse {
    code: u32,
    message: String,
}

/// 获取所有宠物信息
///
/// 这个端点返回系统中所有的宠物信息列表
#[api_v2_operation(
    responses(
        (status = 200, description = "成功获取宠物列表", body = Vec<Pet>),
        (status = 500, description = "服务器内部错误", body = ErrorResponse)
    ),
    tags("pets")
)]
async fn get_pets() -> Result<web::Json<Vec<Pet>>, web::Json<ErrorResponse>> {
    Ok(web::Json(vec![
        Pet {
            id: 1,
            name: "Fluffy".into(),
            tag: Some("cat".into()),
        },
        Pet {
            id: 2,
            name: "Rex".into(),
            tag: Some("dog".into()),
        }
    ]))
}

/// 根据ID获取特定宠物信息
#[api_v2_operation(
    params(
        ("id" = u64, Path, description = "宠物ID")
    ),
    responses(
        (status = 200, description = "成功获取宠物信息", body = Pet),
        (status = 404, description = "宠物不存在", body = ErrorResponse)
    ),
    tags("pets")
)]
async fn get_pet_by_id(pet_id: web::Path<u64>) -> Result<web::Json<Pet>, web::Json<ErrorResponse>> {
    if *pet_id == 1 {
        Ok(web::Json(Pet {
            id: 1,
            name: "Fluffy".into(),
            tag: Some("cat".into()),
        }))
    } else {
        Err(web::Json(ErrorResponse {
            code: 404,
            message: "Pet not found".into(),
        }))
    }
}

/// 添加新宠物
#[api_v2_operation(
    security(
        ("api_key" = [])
    ),
    responses(
        (status = 201, description = "成功创建宠物", body = Pet),
        (status = 400, description = "无效输入", body = ErrorResponse)
    ),
    tags("pets")
)]
async fn add_pet(new_pet: web::Json<Pet>) -> Result<web::Json<Pet>, web::Json<ErrorResponse>> {
    Ok(web::Json(Pet {
        id: new_pet.id,
        name: new_pet.name.clone(),
        tag: new_pet.tag.clone(),
    }))
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            // 启用Paperclip
            .wrap_api()
            // 配置OpenAPI规范路径
            .with_json_spec_at("/api/spec")
            // 配置Swagger UI路径和自定义设置
            .with_swagger_ui_at_with_config("/docs", {
                let mut conf = paperclip::actix::SwaggerUIConfig::default();
                conf.default_models_expand_depth = -1; // 默认折叠所有模型
                conf
            })
            // 注册路由
            .service(
                web::resource("/pets")
                    .route(web::get().to(get_pets))
                    .route(web::post().to(add_pet))
            )
            .service(
                web::resource("/pets/{id}")
                    .route(web::get().to(get_pet_by_id))
            )
            .build()
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

示例说明

1. 数据结构:

   • 定义了Pet和ErrorResponse结构体，并实现了Apiv2Schema trait
   • 使用Serialize和Deserialize来自动序列化/反序列化

2. API端点:

   • get_pets: 获取所有宠物列表
   • get_pet_by_id: 根据ID获取特定宠物
   • add_pet: 添加新宠物

3. 文档生成:

   • 使用#[api_v2_operation]宏添加操作文档
   • 包含响应状态码描述、参数描述和标签
   • 添加了安全定义(api_key)

4. Swagger UI配置:

   • 自定义UI配置，默认折叠所有模型
   • 规范JSON位于/api/spec
   • Swagger UI位于/docs

5. 错误处理:

   • 定义了统一的错误响应结构
   • 每个端点都明确定义了可能的错误响应

这个完整示例展示了如何使用paperclip-actix创建一个有完整文档支持的RESTful API服务，包含了参数文档、响应模型、错误处理和Swagger UI集成等功能。