use std::{collections::BTreeMap, fmt};
use axum::{
Extension, Router,
handler::Handler,
http::Method,
routing::{MethodFilter, MethodRouter, on},
};
use thiserror::Error;
use utoipa::openapi::{OpenApi, path::Parameter};
use crate::{
pagination::{PageLimits, PaginationError},
result::{ClassifyError, ErrorKind},
};
use super::{
contracts::{operations, operations_mut},
cursor_pagination_parameters, offset_pagination_parameters,
};
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum OpenApiRouteError {
#[error("invalid OpenAPI route document: {reason}")]
InvalidDocument {
reason: &'static str,
},
#[error("OpenAPI operation {method} {path} is already registered")]
DuplicateOperation {
method: &'static str,
path: String,
},
#[error("conflicting OpenAPI {kind} component {name}")]
ConflictingComponent {
kind: &'static str,
name: String,
},
#[error("pagination is already configured for this route")]
PaginationAlreadyConfigured,
#[error(transparent)]
InvalidPagination(#[from] PaginationError),
}
impl ClassifyError for OpenApiRouteError {
fn error_kind(&self) -> ErrorKind {
ErrorKind::Validation
}
fn error_code(&self) -> crate::result::ErrorCode {
crate::result::ErrorCode::internal(match self {
Self::InvalidDocument { .. } => "openapi_invalid_route_document",
Self::DuplicateOperation { .. } => "openapi_duplicate_operation",
Self::ConflictingComponent { .. } => "openapi_conflicting_component",
Self::PaginationAlreadyConfigured => "openapi_pagination_already_configured",
Self::InvalidPagination(_) => "openapi_invalid_pagination",
})
}
}
#[must_use]
pub struct OpenApiRoute<S = ()> {
router: MethodRouter<S>,
document: OpenApi,
path: String,
pagination_configured: bool,
}
impl<S> fmt::Debug for OpenApiRoute<S> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("OpenApiRoute")
.field("path", &self.path)
.finish_non_exhaustive()
}
}
impl<S: Clone + Send + Sync + 'static> OpenApiRoute<S> {
pub fn from_handler<H, T>(handler: H, document: OpenApi) -> Result<Self, OpenApiRouteError>
where
H: Handler<T, S>,
T: 'static,
{
if document.paths.paths.len() != 1 {
return Err(OpenApiRouteError::InvalidDocument {
reason: "a handler must describe exactly one path",
});
}
let (path, item) =
document
.paths
.paths
.iter()
.next()
.ok_or(OpenApiRouteError::InvalidDocument {
reason: "missing handler path",
})?;
if !path.starts_with('/') {
return Err(OpenApiRouteError::InvalidDocument {
reason: "handler paths must start with /",
});
}
let mut filter: Option<MethodFilter> = None;
for (method, operation) in operations(item) {
if operation.is_some() {
let method = Method::from_bytes(method.as_bytes()).map_err(|_| {
OpenApiRouteError::InvalidDocument {
reason: "invalid HTTP method",
}
})?;
let next = MethodFilter::try_from(method).map_err(|_| {
OpenApiRouteError::InvalidDocument {
reason: "unsupported HTTP method",
}
})?;
filter = Some(filter.map_or(next, |filter| filter.or(next)));
}
}
let filter = filter.ok_or(OpenApiRouteError::InvalidDocument {
reason: "a handler must describe at least one operation",
})?;
Ok(Self {
path: path.clone(),
router: on(filter, handler),
document,
pagination_configured: false,
})
}
pub fn with_cursor_pagination(self, limits: PageLimits) -> Result<Self, OpenApiRouteError> {
self.with_pagination(limits, cursor_pagination_parameters(limits)?)
}
pub fn with_offset_pagination(self, limits: PageLimits) -> Result<Self, OpenApiRouteError> {
self.with_pagination(limits, offset_pagination_parameters(limits)?)
}
fn with_pagination(
mut self,
limits: PageLimits,
parameters: Vec<Parameter>,
) -> Result<Self, OpenApiRouteError> {
if self.pagination_configured {
return Err(OpenApiRouteError::PaginationAlreadyConfigured);
}
for item in self.document.paths.paths.values_mut() {
for operation in operations_mut(item) {
let target = operation.parameters.get_or_insert_default();
for parameter in ¶meters {
if let Some(existing) = target.iter_mut().find(|existing| {
existing.name == parameter.name
&& existing.parameter_in == parameter.parameter_in
}) {
existing.schema = parameter.schema.clone();
existing.required = parameter.required.clone();
} else {
target.push(parameter.clone());
}
}
}
}
self.router = self.router.layer(Extension(limits));
self.pagination_configured = true;
Ok(self)
}
}
#[must_use]
pub struct OpenApiRouter<S = ()> {
router: Router<S>,
document: OpenApi,
}
impl<S> fmt::Debug for OpenApiRouter<S> {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("OpenApiRouter")
.field("paths", &self.document.paths.paths.len())
.finish_non_exhaustive()
}
}
impl<S: Clone + Send + Sync + 'static> OpenApiRouter<S> {
pub fn new(document: OpenApi) -> Result<Self, OpenApiRouteError> {
if !document.paths.paths.is_empty() {
return Err(OpenApiRouteError::InvalidDocument {
reason: "register paths through route! instead of the base document",
});
}
Ok(Self {
router: Router::new(),
document,
})
}
pub fn route(mut self, route: OpenApiRoute<S>) -> Result<Self, OpenApiRouteError> {
for (path, item) in &route.document.paths.paths {
if let Some(existing) = self.document.paths.paths.get(path) {
for (method, operation) in operations(item) {
if operation.is_some()
&& operations(existing)
.iter()
.any(|(other, operation)| *other == method && operation.is_some())
{
return Err(OpenApiRouteError::DuplicateOperation {
method,
path: path.clone(),
});
}
}
}
}
if let (Some(existing), Some(incoming)) =
(&self.document.components, &route.document.components)
{
check_components("schema", &existing.schemas, &incoming.schemas)?;
check_components("response", &existing.responses, &incoming.responses)?;
check_components(
"security scheme",
&existing.security_schemes,
&incoming.security_schemes,
)?;
}
self.router = self.router.route(&route.path, route.router);
self.document.merge(route.document);
Ok(self)
}
pub fn into_parts(self) -> (Router<S>, OpenApi) {
(self.router, self.document)
}
}
fn check_components<T: PartialEq>(
kind: &'static str,
existing: &BTreeMap<String, T>,
incoming: &BTreeMap<String, T>,
) -> Result<(), OpenApiRouteError> {
for (name, value) in incoming {
if existing.get(name).is_some_and(|existing| existing != value) {
return Err(OpenApiRouteError::ConflictingComponent {
kind,
name: name.clone(),
});
}
}
Ok(())
}
#[macro_export]
macro_rules! openapi_route {
($handler:path $(,)?) => {{
use $crate::http::openapi::utoipa;
#[derive(utoipa::OpenApi)]
#[openapi(paths($handler))]
struct RouteDocument;
$crate::http::openapi::OpenApiRoute::from_handler(
$handler,
<RouteDocument as utoipa::OpenApi>::openapi(),
)
}};
}