feat: generate OpenAPI specification from methods and actions (#194)

Author: DanielleHuisman

Cargo.lock

@@ -54,7 +54,7 @@ async fn main() {
     let api_router = OpenApiRouter::new()
         .route("/protected", get(async || "Protected"))
         .route_layer(from_fn(auth_required::<User>))
-        .nest("/auth", AuthRoutes::openapi_router::<User, ()>());
+        .nest("/auth", AuthRoutes::new(shield).openapi_router());
 
     // Initialize router
     let (router, openapi) = OpenApiRouter::new()

examples/axum/src/main.rs

@@ -4,10 +4,7 @@ async fn main() {
     use std::sync::Arc;
 
     use axum::{Router, middleware::from_fn, routing::get};
-    use leptos::{
-        config::{LeptosOptions, get_configuration},
-        context::provide_context,
-    };
+    use leptos::{config::get_configuration, context::provide_context};
     use leptos_axum::{LeptosRoutes, generate_route_list};
     use shield::{Shield, ShieldOptions};
     use shield_bootstrap::BootstrapLeptosStyle;
@@ -62,7 +59,7 @@ async fn main() {
     let router = Router::new()
         .route("/api/protected", get(async || "Protected"))
         .route_layer(from_fn(auth_required::<User>))
-        .nest("/api/auth", AuthRoutes::router::<User, LeptosOptions>())
+        .nest("/api/auth", AuthRoutes::new(shield).router())
         .leptos_routes_with_context(
             &leptos_options,
             routes,

examples/leptos-axum/src/main.rs

@@ -16,6 +16,7 @@ utoipa = ["dep:utoipa"]
 async-trait.workspace = true
 bon.workspace = true
 chrono = { workspace = true, features = ["serde"] }
+convert_case = "0.8.0"
 futures.workspace = true
 serde = { workspace = true, features = ["derive"] }
 serde_json.workspace = true

packages/core/shield/Cargo.toml

@@ -1,8 +1,5 @@
 use std::any::Any;
 
-use async_trait::async_trait;
-use serde::{Deserialize, Serialize};
-
 use crate::{
     error::ShieldError,
     form::Form,
@@ -11,6 +8,38 @@ use crate::{
     response::Response,
     session::{BaseSession, MethodSession},
 };
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+#[cfg(feature = "utoipa")]
+use utoipa::openapi::HttpMethod;
+
+#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
+pub enum ActionMethod {
+    Get,
+    Post,
+    Put,
+    Delete,
+    Options,
+    Head,
+    Patch,
+    Trace,
+}
+
+#[cfg(feature = "utoipa")]
+impl From<ActionMethod> for HttpMethod {
+    fn from(value: ActionMethod) -> Self {
+        match value {
+            ActionMethod::Get => Self::Get,
+            ActionMethod::Post => Self::Post,
+            ActionMethod::Put => Self::Put,
+            ActionMethod::Delete => Self::Delete,
+            ActionMethod::Options => Self::Options,
+            ActionMethod::Head => Self::Head,
+            ActionMethod::Patch => Self::Patch,
+            ActionMethod::Trace => Self::Trace,
+        }
+    }
+}
 
 // TODO: Think of a better name.
 #[derive(Clone, Debug, Deserialize, Serialize)]
@@ -46,6 +75,12 @@ pub trait Action<P: Provider, S>: ErasedAction + Send + Sync {
 
     fn name(&self) -> String;
 
+    fn openapi_summary(&self) -> &'static str;
+
+    fn openapi_description(&self) -> &'static str;
+
+    fn method(&self) -> ActionMethod;
+
     fn condition(&self, _provider: &P, _session: &MethodSession<S>) -> Result<bool, ShieldError> {
         Ok(true)
     }
@@ -66,6 +101,12 @@ pub trait ErasedAction: Send + Sync {
 
     fn erased_name(&self) -> String;
 
+    fn erased_openapi_summary(&self) -> &'static str;
+
+    fn erased_openapi_description(&self) -> &'static str;
+
+    fn erased_method(&self) -> ActionMethod;
+
     fn erased_condition(
         &self,
         provider: &(dyn Any + Send + Sync),
@@ -100,6 +141,18 @@ macro_rules! erased_action {
                 self.name()
             }
 
+            fn erased_openapi_summary(&self) -> &'static str {
+                self.openapi_summary()
+            }
+
+            fn erased_openapi_description(&self) -> &'static str {
+                self.openapi_description()
+            }
+
+            fn erased_method(&self) -> $crate::ActionMethod {
+                self.method()
+            }
+
             fn erased_condition(
                 &self,
                 provider: &(dyn std::any::Any + Send + Sync),

packages/core/shield/src/action.rs

@@ -3,6 +3,9 @@ use crate::{Form, Input, InputType, InputTypeSubmit, MethodSession, Provider, Sh
 const ACTION_ID: &str = "sign-out";
 const ACTION_NAME: &str = "Sign out";
 
+// TODO: Sign out should be a global action that is independent of the method.
+// TODO: Add hooks, so the method can still perform custom sign out.
+
 pub struct SignOutAction;
 
 impl SignOutAction {

packages/core/shield/src/actions/sign_out.rs

@@ -4,6 +4,7 @@ mod error;
 mod form;
 mod method;
 mod options;
+mod path;
 mod provider;
 mod request;
 mod response;
@@ -19,6 +20,7 @@ pub use error::*;
 pub use form::*;
 pub use method::*;
 pub use options::*;
+pub use path::*;
 pub use provider::*;
 pub use request::*;
 pub use response::*;

packages/core/shield/src/lib.rs

@@ -1,13 +1,24 @@
 use std::{any::Any, collections::HashMap, sync::Arc};
 
+#[cfg(feature = "utoipa")]
+use convert_case::{Case, Casing};
 use futures::future::try_join_all;
-use tracing::{debug, warn};
+use tracing::warn;
+#[cfg(feature = "utoipa")]
+use utoipa::{
+    IntoParams,
+    openapi::{
+        OpenApi, PathItem, Paths,
+        path::{Operation, ParameterIn},
+    },
+};
 
 use crate::{
     action::{ActionForms, ActionMethodForm, ActionProviderForm},
     error::{ActionError, MethodError, ProviderError, SessionError, ShieldError},
     method::ErasedMethod,
     options::ShieldOptions,
+    path::ActionPathParams,
     request::Request,
     response::ResponseType,
     session::Session,
@@ -184,16 +195,12 @@ impl<U: User> Shield<U> {
             .erased_call(provider, &base_session, &*method_session, request)
             .await?;
 
-        debug!("response {:#?}", response);
-
         for session_action in &response.session_actions {
             session_action
                 .call(method_id, provider_id, &session)
                 .await?;
         }
 
-        debug!("session actions processed");
-
         Ok(response.r#type)
     }
 
@@ -232,6 +239,49 @@ impl<U: User> Shield<U> {
             None => Ok(None),
         }
     }
+
+    #[cfg(feature = "utoipa")]
+    pub fn openapi(&self) -> OpenApi {
+        let mut paths = Paths::builder();
+
+        for method in self.methods.values() {
+            for action in method.erased_actions() {
+                use utoipa::openapi::Response;
+
+                let method_id = method.erased_id();
+                let action_id = action.erased_id();
+
+                // TODO: Query, request body, responses.
+
+                paths = paths.path(
+                    format!("/{}/{}/{{providerId}}", method_id, action_id),
+                    PathItem::builder()
+                        .operation(
+                            action.erased_method().into(),
+                            Operation::builder()
+                                .operation_id(Some(format!(
+                                    "{}{}",
+                                    action_id.to_case(Case::Camel),
+                                    method_id.to_case(Case::UpperCamel)
+                                )))
+                                .summary(Some(action.erased_openapi_summary()))
+                                .description(Some(action.erased_openapi_description()))
+                                .tag("auth")
+                                .parameters(Some(ActionPathParams::into_params(|| {
+                                    Some(ParameterIn::Path)
+                                })))
+                                .response(
+                                    "500",
+                                    Response::builder().description("Internal server error."),
+                                ),
+                        )
+                        .build(),
+                );
+            }
+        }
+
+        OpenApi::builder().paths(paths.build()).build()
+    }
 }
 
 #[cfg(test)]

…ges/integrations/shield-axum/src/path.rs packages/core/shield/src/path.rspackages/integrations/shield-axum/src/path.rs renamed to packages/core/shield/src/path.rs packages/integrations/shield-axum/src/path.rs renamed to packages/core/shield/src/path.rs

@@ -1,7 +1,6 @@
 mod error;
 mod extract;
 mod middleware;
-mod path;
 mod router;
 mod routes;