如何在utoipa中为可选查询参数生成正确的OpenAPI Schema？

核心原因与解决方案 #

utoipa 对 Option<T> 类型的查询参数默认应该自动标记为可选，但部分场景下（比如依赖版本过旧、结构体派生配置缺失）会出现推断错误。以下是具体解决步骤：

1. 确保依赖版本为最新 #

更新 Cargo.toml 中的 utoipa 相关依赖到当前稳定版，旧版本存在Option字段误判为必填的bug：

[package]
name = "your-api-project"
version = "0.1.0"
edition = "2021"

[dependencies]
actix-web = "4.4.0"
serde = { version = "1.0", features = ["derive"] }
utoipa = "3.4.0"
utoipa-swagger-ui = "3.4.0"

2. 修正查询参数结构体配置 #

在查询参数结构体上显式指定参数位置，并为Option字段添加#[param(optional)]标记（强制覆盖推断逻辑）：

use utoipa::IntoParams;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, IntoParams)]
#[into_params(parameter_in = Query)] // 明确指定为查询参数
pub struct UserListQuery {
    #[param(optional)]
    pub page: Option<u32>,
    #[param(optional)]
    pub size: Option<u32>,
}

3. 确认接口路由的参数引用 #

确保接口的utoipa::path宏中正确引用查询参数结构体：

use actix_web::{get, web, HttpResponse};
use utoipa::path;

#[path(
    get,
    path = "/api/users",
    params(UserListQuery),
    responses(
        (status = 200, description = "用户列表", body = Vec<User>)
    )
)]
#[get("/api/users")]
async fn get_users(query: web::Query<UserListQuery>) -> HttpResponse {
    // 业务逻辑实现
    HttpResponse::Ok().json(vec![])
}

验证结果 #

修正后生成的OpenAPI Schema中，对应参数的required字段会被设为false，示例片段：

"parameters": [
  {
    "name": "page",
    "in": "query",
    "schema": {
      "type": "integer",
      "format": "uint32"
    },
    "required": false
  },
  {
    "name": "size",
    "in": "query",
    "schema": {
      "type": "integer",
      "format": "uint32"
    },
    "required": false
  }
]

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