Compile-time Axum responses derived from enum annotations

[leebenson]

Hey! Hoping someone can guide me please.

I'm trying to get something as closely resembling Poem's OpenAPI implementation as I can, using Axum + Utoipa.

i.e. I want to avoid writing both Axum IntoResponse blocks and manual Utoipa responses = (...) that basically repeat the same thing. It's so easy for them to fall out of sync.

My first thought was: I'll write a proc macro that annotates success/error enums like this:

#[derive(Debug, From, IntoResponse)]
pub enum RegisterError {
    #[api(status = 422)]
    #[from(InputErrors)]
    Unprocessable(RegisterUnprocessable),

    #[api(status = 500, error)]
    #[from]
    Error(anyhow::Error),
}

And then my Axum handlers would be something like this...

#[handler(state = Context, path = "/bla", method = "get")]
async fn some_handler(Json(some_param): Json<SomeStruct>) -> Result<Success, RegisterError>

This would generate both:

1. Axum's IntoResponse impl, using the response codes and JSON bodis (where applicable).
2. Utoipa's OpenAPI definitions.

... but then I discovered #433 and related work, which seems to do almost exactly this, at least for the Utoipa part.

The part I haven't figure out yet is the interplay with Axum.

I wondered if you have any guidance on how to approach this? It seems like a lot of the macro machinery is there already, but I can't seem to figure out how to put it all together into a single handler example.

My goal is to stop having to have compile-time verification of handler params + responses that is guaranteed to remain in sync between what Axum expects and what OpenAPI definitions advertise!

Thanks!

[juhaku]

This is not yet fully there yet in utoipa as the fn return types are not yet evaluated as responses which can be automatically collected. But for example I have done something like this before with utoipa 4.x.x. This could be extend to Result<T, E> type of responses as well, but then the axum::IntoResponse need to be also implemented for both of the types T and E as well.

#[derive(IntoResponses)]
pub enum LoginResponse {
    /// Successful login
    #[response(
        status = OK,
        headers(
            ("Authorization" = String, description = "Access token of successfull login")
        )
    )]
    Ok((String, String)),
    /// Unauthorized to access to the service
    #[response(status = BAD_REQUEST)]
    Unauthorized(String),
}

impl IntoResponse for LoginResponse {
    fn into_response(self) -> axum::response::Response {
        match self {
            Self::Ok((token, id)) => (
                StatusCode::OK,
                [
                    (header::CONTENT_TYPE, "text/plain"),
                    (header::AUTHORIZATION, token.as_str()),
                ],
                id,
            )
                .into_response(),
            Self::Unauthorized(error) => (StatusCode::BAD_REQUEST, error).into_response(),
        }
    }
}

#[utoipa::path(
    post,
    context_path = "/user",
    path = "/login",
    request_body = LoginRequest,
    responses(LoginResponse),
)]
#[axum::debug_handler]
async fn login(
    State(user_service): State<UserService>,
    Json(login_request): Json<LoginRequest>,
) -> LoginResponse {
    user_repository
        .find_user_by_name(&login_request.username)
        .map_err(LoginError::UnexpectedSqlxError)
        .and_then(|user| async {
            if let Some(user) = user {
                Ok(user.0)
            } else {
                Err(LoginError::NotFound(login_request.username.to_string()))
            }
        })
        .and_then(|user| async move {
            match futures::try_join!(
                verify_password(login_request.password.as_bytes(), &user.password_hash),
                validate_secret_key(
                    mem::take(&mut user.secret_key.into_inner()),
                    login_request.secret_key.as_str()
                )
            ) {
                Ok(_) => Ok(user.id),
                Err(error) => Err(error),
            }
        })
        .and_then(|id| async {
            token_service
                .generate_token(login_request.username.clone(), SECRET_KEY.as_bytes())
                .await
                .map_err(Into::into)
                .map(|token| (token, id))
        })
        .await
        .map_or_else(
            |error| {
                tracing::error!("Failed to login {error}");
                LoginResponse::Unauthorized(LoginError::Unauthorized.to_string())
            },
            LoginResponse::Ok,
        )
}

Hope this helps. @leebenson

[leebenson]

That helps a lot, thank you!

Is there already a blanket implementation for Result<T, E> where T: IntoResponses, E: IntoResponses?

[juhaku]

Actually yes, if you enable feature flag auto_into_responses But this is highly experimental and probably due for change in future as the implementation for utoipa-gen side has not been fully thought true. I don't remember how far the implementation is implemented for the responses and what side effects enabling the feature will add.

#[cfg(feature = "auto_into_responses")]
impl<T: IntoResponses, E: IntoResponses> IntoResponses for Result<T, E> {
    fn responses() -> BTreeMap<String, openapi::RefOr<openapi::response::Response>> {
        let mut responses = T::responses();
        responses.append(&mut E::responses());

        responses
    }
}

#[cfg(feature = "auto_into_responses")]
impl IntoResponses for () {
    fn responses() -> BTreeMap<String, openapi::RefOr<openapi::response::Response>> {
        BTreeMap::new()
    }
}