use utoipa::{
IntoParams,
openapi::{
Required,
path::{Parameter, ParameterBuilder, ParameterIn},
schema::{ObjectBuilder, Type},
},
};
use crate::{
http::{
CursorPagination, CursorPaginationQuery, IDEMPOTENCY_KEY_HEADER_NAME,
IdempotencyRequestPolicy, MAX_IDEMPOTENCY_KEY_LENGTH, OffsetPagination,
OffsetPaginationQuery, QueryParams, RequiredIdempotencyKey,
},
pagination::{PageLimits, PaginationError},
};
pub fn cursor_pagination_parameters(limits: PageLimits) -> Result<Vec<Parameter>, PaginationError> {
Ok(cursor_parameters(limits.validate()?))
}
pub fn offset_pagination_parameters(limits: PageLimits) -> Result<Vec<Parameter>, PaginationError> {
Ok(offset_parameters(limits.validate()?))
}
fn page_size(limits: PageLimits) -> Parameter {
query_parameter(
"page_size",
"Maximum number of items returned.",
ObjectBuilder::new()
.schema_type(Type::Integer)
.minimum(Some(1))
.maximum(Some(limits.max_page_size()))
.default(Some(limits.default_page_size().into())),
)
}
fn cursor_parameters(limits: PageLimits) -> Vec<Parameter> {
vec![
page_size(limits),
query_parameter(
"cursor",
"Opaque cursor from the previous page.",
ObjectBuilder::new()
.schema_type(Type::String)
.min_length(Some(1))
.max_length(Some(limits.max_cursor_length()))
.pattern(Some(r"^[A-Za-z0-9_.-]+$")),
),
query_parameter(
"include_total",
"Whether to request the total item count.",
ObjectBuilder::new()
.schema_type(Type::Boolean)
.default(Some(false.into())),
),
]
}
fn offset_parameters(limits: PageLimits) -> Vec<Parameter> {
vec![
query_parameter(
"page",
"One-based page number.",
ObjectBuilder::new()
.schema_type(Type::Integer)
.minimum(Some(1))
.maximum(Some(u32::MAX))
.default(Some(1.into())),
),
page_size(limits),
]
}
fn query_parameter(name: &str, description: &str, schema: ObjectBuilder) -> Parameter {
ParameterBuilder::new()
.name(name)
.parameter_in(ParameterIn::Query)
.required(Required::False)
.description(Some(description))
.schema(Some(schema))
.build()
}
#[must_use]
pub fn idempotency_key_parameter(policy: IdempotencyRequestPolicy) -> Option<Parameter> {
let required = match policy {
IdempotencyRequestPolicy::Disabled => return None,
IdempotencyRequestPolicy::HeaderOptional => Required::False,
IdempotencyRequestPolicy::Required => Required::True,
};
let schema = ObjectBuilder::new()
.schema_type(Type::String)
.min_length(Some(1))
.max_length(Some(MAX_IDEMPOTENCY_KEY_LENGTH))
.pattern(Some(r"^[A-Za-z0-9_.:-]+$"));
Some(
ParameterBuilder::new()
.name(IDEMPOTENCY_KEY_HEADER_NAME)
.parameter_in(ParameterIn::Header)
.required(required)
.description(Some(
"Identifies one operation within its scope. Reuse only for an identical request.",
))
.schema(Some(schema))
.build(),
)
}
impl IntoParams for CursorPaginationQuery {
fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
cursor_parameters(PageLimits::default())
}
}
impl IntoParams for CursorPagination {
fn into_params(provider: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
CursorPaginationQuery::into_params(provider)
}
}
impl IntoParams for OffsetPaginationQuery {
fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
offset_parameters(PageLimits::default())
}
}
impl IntoParams for OffsetPagination {
fn into_params(provider: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
OffsetPaginationQuery::into_params(provider)
}
}
impl<T: IntoParams> IntoParams for QueryParams<T> {
fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
T::into_params(|| Some(ParameterIn::Query))
}
}
impl IntoParams for RequiredIdempotencyKey {
fn into_params(_: impl Fn() -> Option<ParameterIn>) -> Vec<Parameter> {
idempotency_key_parameter(IdempotencyRequestPolicy::Required)
.into_iter()
.collect()
}
}