utoipa项目中Optional参数在Swagger UI显示为Required的解决方案

在使用utoipa这个Rust Web框架的OpenAPI/Swagger文档生成工具时，开发者可能会遇到一个常见问题：即使将结构体字段定义为Option类型，并在Swagger UI中期望它们显示为可选参数，这些参数却仍然被标记为"required"。

问题现象

当开发者定义如下结构体时：

#[derive(Clone, Debug, Default, Serialize, Deserialize, IntoParams)]
pub struct PageRequest {
    /// 每页最大返回结果数
    /// 如果省略，每个路由可能有自己的默认值
    #[serde(default)]
    #[param(required = false)]
    pub limit: Option<u64>,

    /// 分页令牌，如果请求者之前获得了分页响应
    #[serde(default)]
    pub page_token: Option<String>,
}

尽管字段都使用了Option类型，并且显式设置了#[param(required = false)]，生成的Swagger UI仍然将这些参数标记为必填项（带有红色星号）。

问题原因

这个问题源于utoipa在处理查询参数时的默认行为。当使用IntoParams派生宏时，如果没有明确指定参数的位置（如查询参数、路径参数等），utoipa可能会采用默认行为，导致参数被错误地标记为必填。

解决方案

解决这个问题的方法是在结构体上添加#[into_params(parameter_in = Query)]属性，明确指定这些参数是查询参数：

#[derive(Clone, Debug, Default, Serialize, Deserialize, IntoParams)]
#[into_params(parameter_in = Query)]
pub struct PageRequest {
    /// 每页最大返回结果数
    /// 如果省略，每个路由可能有自己的默认值
    #[serde(default)]
    pub limit: Option<u64>,

    /// 分页令牌，如果请求者之前获得了分页响应
    #[serde(default)]
    pub page_token: Option<String>,
}

通过这种方式，utoipa会正确识别这些参数是可选的查询参数，Swagger UI也会相应地显示它们为可选参数。

深入理解

1. 参数位置的重要性：在OpenAPI规范中，参数的位置（查询、路径、头部等）会影响其必填性。路径参数默认是必填的，而查询参数默认是可选的。

2. utoipa的行为：当不指定parameter_in时，utoipa可能无法正确推断参数的上下文，导致默认标记为必填。明确指定参数位置可以避免这种歧义。

3. 最佳实践：对于所有将用作API参数的结构体，建议总是明确指定parameter_in属性，以确保生成的OpenAPI文档符合预期。

扩展知识

在实际开发中，正确处理可选参数对于API的灵活性和用户体验至关重要。通过utoipa提供的属性，开发者可以精确控制API文档的生成，包括：

• 参数是否必填
• 参数的默认值
• 参数的描述文档
• 参数的验证规则

掌握这些技巧可以帮助开发者生成更准确、更有用的API文档，提升API的易用性和可维护性。