在 utoipa 中使用自定义 JSON 验证器生成 OpenAPI 文档

在 Rust Web 开发中，我们经常需要对请求体进行 JSON 反序列化和验证。使用 axum 框架时，开发者可能会创建自定义的 JSON 验证器来统一处理这些逻辑。本文将介绍如何在 utoipa 项目中正确使用自定义 JSON 验证器并生成完整的 OpenAPI 文档。

自定义 JSON 验证器的实现

首先，我们来看一个典型的自定义 JSON 验证器实现：

pub struct ValidateJson<T>(pub T);

#[async_trait]
impl<T, S> FromRequest<S> for ValidateJson<T>
where
    T: DeserializeOwned + Validate,
    S: Send + Sync,
{
    type Rejection = AppError;

    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
        let Json(value) = Json::<T>::from_request(req, state)
            .await
            .map_err(AppError::AxumJsonRejection)?;
        value.validate().map_err(AppError::ValidationError)?;
        Ok(ValidateJson(value))
    }
}

这个验证器做了两件事：

1. 使用 axum 的 Json 提取器进行反序列化
2. 对反序列化后的值进行验证（使用 validator crate 的 Validate trait）

数据结构定义

接着我们定义一个需要验证的数据结构：

#[derive(Serialize, Deserialize, Debug, ToSchema, Validate)]
pub struct MyStruct {
    #[validate(range(min = 1, max = 24))]
    pub interval: i32,
}

这个结构体使用了 validator 的验证宏来确保 interval 字段的值在 1 到 24 之间。

处理函数实现

在路由处理函数中使用我们的自定义验证器：

pub async fn handler(
    State(service): State<Arc<Service>>,
    ValidateJson(body): ValidateJson<MyStruct>,
) -> Result<(), AppError> {
    Ok(())
}

OpenAPI 文档生成问题

当我们尝试为这个处理函数生成 OpenAPI 文档时，会遇到一个问题：utoipa 无法自动识别 ValidateJson 包装器中的实际类型。这是因为 utoipa 的宏处理器无法从 token 流中推断出 ValidateJson 内部的具体类型。

解决方案

为了解决这个问题，我们需要显式指定请求体类型。在 utoipa 的 path 宏中使用 request_body 参数：

#[utoipa::path(
    post,
    path="/api",
    request_body=MyStruct,
    responses(
        (status=200, description="Api"),
        (status=400, description="App error"),
    )
)]
pub async fn handler(
    State(service): State<Arc<Service>>,
    ValidateJson(body): ValidateJson<MyStruct>,
) -> Result<(), AppError> {
    Ok(())
}

通过这种方式，我们既保持了自定义验证器的功能，又确保了 OpenAPI 文档的正确生成。

深入理解

这种限制的原因是 Rust 的宏系统在编译时无法深入分析类型包装器的内部结构。utoipa 需要明确的类型信息来生成准确的 OpenAPI 规范。request_body 参数提供了一种显式指定类型的方式，确保了文档生成的准确性。

在实际项目中，这种模式非常有用，因为它：

1. 集中了验证逻辑
2. 保持了代码的整洁性
3. 确保了 API 文档的准确性
4. 提供了统一的错误处理机制

通过理解这些原理，开发者可以更好地设计自己的 Web API，并确保文档与实现保持同步。