feat: add serde and utoipa support

DanielleHuisman · DanielleHuisman · commit 96f8e92c89b8 · 2025-12-10T18:19:57.000+01:00
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,5 +1,5 @@
 [workspace]
-members = ["example", "packages/*"]
+members = ["examples/*", "packages/*"]
 resolver = "2"
 
 [workspace.package]
@@ -16,6 +16,7 @@ regex = "1.12.2"
 serde = "1.0.228"
 serde_json = "1.0.145"
 tokio = "1.48.0"
+utoipa = "5.4.0"
 
 [workspace.lints.rust]
 unsafe_code = "deny"
diff --git a/deny.toml b/deny.toml
@@ -2,15 +2,17 @@
 all-features = true
 
 [advisories]
-ignore = []
+ignore = [
+    { id = "RUSTSEC-2024-0436", reason = "No maintained version available for `paste`." },
+]
 
 [bans]
 allow-wildcard-paths = true
 multiple-versions = "allow"
 wildcards = "deny"
 
 [licenses]
-allow = ["MIT", "Unicode-3.0"]
+allow = ["Apache-2.0", "BSD-3-Clause", "MIT", "Unicode-3.0"]
 confidence-threshold = 1.0
 
 [sources]
diff --git a/examples/basic/Cargo.toml b/examples/basic/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
-name = "fortifier-example"
-description = "Fortifier example."
+name = "fortifier-example-basic"
+description = "Fortifier basic example."
 
 authors.workspace = true
 edition.workspace = true
diff --git a/examples/basic/src/email_address.rs b/examples/basic/src/email_address.rs
diff --git a/examples/basic/src/main.rs b/examples/basic/src/main.rs
diff --git a/examples/basic/src/user.rs b/examples/basic/src/user.rs
diff --git a/examples/server/Cargo.toml b/examples/server/Cargo.toml
@@ -0,0 +1,29 @@
+[package]
+name = "fortifier-example-server"
+description = "Fortifier server example."
+
+authors.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+version.workspace = true
+
+[dependencies]
+axum = "0.8.7"
+fortifier = { workspace = true, features = [
+    "email",
+    "regex",
+    "serde",
+    "url",
+    "utoipa",
+] }
+serde = { workspace = true, features = ["derive"] }
+thiserror = "2.0.17"
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+utoipa = { workspace = true, features = ["axum_extras", "uuid"] }
+utoipa-axum = "0.2.0"
+utoipa-scalar = { version = "0.3.0", features = ["axum"] }
+uuid = { version = "1.19.0", features = ["serde", "v7"] }
+
+[lints]
+workspace = true
diff --git a/examples/server/src/main.rs b/examples/server/src/main.rs
@@ -0,0 +1,24 @@
+mod routes;
+mod user;
+
+use std::{
+    error::Error,
+    net::{IpAddr, Ipv4Addr, SocketAddr},
+};
+
+use tokio::net::TcpListener;
+
+use crate::routes::Routes;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let router = Routes::router();
+
+    let address = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
+    let listener = TcpListener::bind(&address).await?;
+
+    println!("listening on http://{}", &address);
+    axum::serve(listener, router).await?;
+
+    Ok(())
+}
diff --git a/examples/server/src/routes.rs b/examples/server/src/routes.rs
@@ -0,0 +1,30 @@
+use axum::{Json, Router, routing::get};
+use utoipa::OpenApi;
+use utoipa_axum::router::OpenApiRouter;
+use utoipa_scalar::{Scalar, Servable};
+
+use crate::user::routes::UserRoutes;
+
+#[derive(OpenApi)]
+#[openapi(info(
+    title = "Fortifier Example API",
+    description = "Example to showcase Fortifier validation.",
+))]
+pub struct Routes;
+
+impl Routes {
+    pub fn router<S>() -> Router<S>
+    where
+        S: Clone + Send + Sync + 'static,
+    {
+        let router = OpenApiRouter::new().merge(UserRoutes::router());
+
+        let (router, openapi) = OpenApiRouter::with_openapi(Routes::openapi())
+            .nest("/api/v1", router)
+            .split_for_parts();
+
+        router
+            .merge(Scalar::with_url("/api/reference", openapi.clone()))
+            .route("/api/v1/openapi.json", get(|| async { Json(openapi) }))
+    }
+}
diff --git a/examples/server/src/user.rs b/examples/server/src/user.rs
@@ -0,0 +1,3 @@
+pub mod entities;
+pub mod routes;
+pub mod schemas;
diff --git a/examples/server/src/user/entities.rs b/examples/server/src/user/entities.rs
@@ -0,0 +1,12 @@
+pub mod user {
+    use serde::Serialize;
+    use utoipa::ToSchema;
+    use uuid::Uuid;
+
+    #[derive(Serialize, ToSchema)]
+    pub struct Model {
+        pub id: Uuid,
+        pub email_address: String,
+        pub name: String,
+    }
+}
diff --git a/examples/server/src/user/routes.rs b/examples/server/src/user/routes.rs
@@ -0,0 +1,61 @@
+use axum::{Json, http::StatusCode, response::IntoResponse};
+use fortifier::{Validate, ValidationErrors};
+use thiserror::Error;
+use utoipa_axum::{router::OpenApiRouter, routes};
+use uuid::Uuid;
+
+use crate::user::{
+    entities::user,
+    schemas::{CreateUser, CreateUserValidationError},
+};
+
+pub struct UserRoutes;
+
+impl UserRoutes {
+    pub fn router<S>() -> OpenApiRouter<S>
+    where
+        S: Clone + Send + Sync + 'static,
+    {
+        OpenApiRouter::new().routes(routes!(create_user))
+    }
+}
+
+#[derive(Debug, Error)]
+enum CreateUserError {
+    #[error(transparent)]
+    UnprocessableContent(#[from] ValidationErrors<CreateUserValidationError>),
+}
+
+impl IntoResponse for CreateUserError {
+    fn into_response(self) -> axum::response::Response {
+        todo!()
+    }
+}
+
+#[utoipa::path(
+    post,
+    path = "/users",
+    operation_id = "createUser",
+    summary = "Create user",
+    description = "Create a user.",
+    tags = ["User"],
+    request_body = CreateUser,
+    responses(
+        (status = 201, description = "The created user.", body = user::Model),
+        (status = 400, description = "Validation error.", body = ValidationErrors<CreateUserValidationError>),
+        // (status = 500, description = "Internal server error.", body = ErrorBody),
+    )
+)]
+async fn create_user(
+    Json(data): Json<CreateUser>,
+) -> Result<(StatusCode, Json<user::Model>), CreateUserError> {
+    data.validate().await?;
+
+    let user = user::Model {
+        id: Uuid::now_v7(),
+        email_address: data.email_address,
+        name: data.name,
+    };
+
+    Ok((StatusCode::CREATED, Json(user)))
+}
diff --git a/examples/server/src/user/schemas.rs b/examples/server/src/user/schemas.rs
@@ -0,0 +1,12 @@
+use fortifier::Validate;
+use serde::Deserialize;
+use utoipa::ToSchema;
+
+#[derive(Deserialize, ToSchema, Validate)]
+pub struct CreateUser {
+    #[validate(email)]
+    pub email_address: String,
+
+    #[validate(length(min = 1, max = 256))]
+    pub name: String,
+}
diff --git a/packages/fortifier-macros/Cargo.toml b/packages/fortifier-macros/Cargo.toml
@@ -11,8 +11,14 @@ version.workspace = true
 [lib]
 proc-macro = true
 
+[features]
+default = []
+serde = []
+utoipa = []
+
 [dependencies]
 convert_case = "0.9.0"
+proc-macro-crate = "3.4.0"
 proc-macro2 = "1.0.103"
 quote = "1.0.42"
 syn = "2.0.110"
diff --git a/packages/fortifier-macros/src/validate.rs b/packages/fortifier-macros/src/validate.rs
@@ -1,3 +1,4 @@
+mod attributes;
 mod r#enum;
 mod field;
 mod fields;
diff --git a/packages/fortifier-macros/src/validate/attributes.rs b/packages/fortifier-macros/src/validate/attributes.rs
@@ -0,0 +1,38 @@
+use proc_macro2::TokenStream;
+use quote::quote;
+
+pub fn enum_attributes() -> TokenStream {
+    let mut attributes: Vec<TokenStream> = vec![];
+
+    #[cfg(feature = "serde")]
+    {
+        use proc_macro_crate::crate_name;
+
+        if crate_name("serde").is_ok() {
+            attributes.push(quote! {
+                #[derive(serde::Deserialize, serde::Serialize)]
+                #[serde(
+                    // TODO: Tag?
+                    tag = "path",
+                    rename_all = "camelCase",
+                    rename_all_fields = "camelCase"
+                )]
+            });
+        }
+    }
+
+    #[cfg(feature = "utoipa")]
+    {
+        use proc_macro_crate::crate_name;
+
+        if crate_name("utoipa").is_ok() {
+            attributes.push(quote! {
+                #[derive(utoipa::ToSchema)]
+            });
+        }
+    }
+
+    quote! {
+        #( #attributes )*
+    }
+}
diff --git a/packages/fortifier-macros/src/validate/enum.rs b/packages/fortifier-macros/src/validate/enum.rs
@@ -4,6 +4,7 @@ use syn::{DataEnum, DeriveInput, Generics, Ident, Result, Variant, Visibility};
 
 use crate::{
     validate::{
+        attributes::enum_attributes,
         field::{LiteralOrIdent, ValidateFieldPrefix},
         fields::ValidateFields,
     },
@@ -44,6 +45,7 @@ impl ValidateEnum {
         let visibility = &self.visibility;
         let error_ident = &self.error_ident;
 
+        let attributes = enum_attributes();
         let error_variant_idents = self
             .variants
             .iter()
@@ -60,6 +62,7 @@ impl ValidateEnum {
             quote! {
                 #[allow(dead_code)]
                 #[derive(Debug)]
+                #attributes
                 #visibility enum #error_ident {
                     #( #error_variant_idents(#error_variant_types) ),*
                 }
diff --git a/packages/fortifier-macros/src/validate/field.rs b/packages/fortifier-macros/src/validate/field.rs
@@ -4,6 +4,7 @@ use quote::{ToTokens, format_ident, quote};
 use syn::{Field, Ident, Result, Visibility};
 
 use crate::{
+    validate::attributes::enum_attributes,
     validation::{Execution, Validation},
     validations::{Custom, Email, Length, Regex, Url},
 };
@@ -103,6 +104,7 @@ impl ValidateField {
 
     pub fn error_type(&self, ident: &Ident) -> (TokenStream, Option<TokenStream>) {
         if self.validations.len() > 1 {
+            let attributes = enum_attributes();
             let visibility = &self.visibility;
             let ident = format_ident!("{}{}ValidationError", ident, self.error_ident);
             let variant_ident = self.validations.iter().map(|validation| validation.ident());
@@ -115,6 +117,7 @@ impl ValidateField {
                 ident.to_token_stream(),
                 Some(quote! {
                     #[derive(Debug)]
+                    #attributes
                     #visibility enum #ident {
                         #( #variant_ident(#variant_type) ),*
                     }
diff --git a/packages/fortifier-macros/src/validate/fields.rs b/packages/fortifier-macros/src/validate/fields.rs
@@ -3,7 +3,10 @@ use quote::{ToTokens, format_ident, quote};
 use syn::{Fields, FieldsNamed, FieldsUnnamed, Ident, Result, Visibility};
 
 use crate::{
-    validate::field::{LiteralOrIdent, ValidateField, ValidateFieldPrefix},
+    validate::{
+        attributes::enum_attributes,
+        field::{LiteralOrIdent, ValidateField, ValidateFieldPrefix},
+    },
     validation::Execution,
 };
 
@@ -194,6 +197,8 @@ fn error_type<'a>(
     error_ident: &Ident,
     fields: impl Iterator<Item = &'a ValidateField>,
 ) -> (TokenStream, TokenStream) {
+    let attributes = enum_attributes();
+
     let mut error_field_idents = vec![];
     let mut error_field_types = vec![];
     let mut error_field_enums = vec![];
@@ -214,6 +219,7 @@ fn error_type<'a>(
         quote! {
             #[allow(dead_code)]
             #[derive(Debug)]
+            #attributes
             #visibility enum #error_ident {
                 #( #error_field_idents(#error_field_types) ),*
             }
diff --git a/packages/fortifier/Cargo.toml b/packages/fortifier/Cargo.toml
@@ -15,8 +15,9 @@ indexmap = ["dep:indexmap"]
 macros = ["dep:fortifier-macros"]
 message = []
 regex = ["dep:regex"]
-serde = ["dep:serde", "email_address/serde_support"]
+serde = ["dep:serde", "email_address?/serde_support", "fortifier-macros?/serde"]
 url = ["dep:url"]
+utoipa = ["dep:utoipa", "fortifier-macros?/utoipa"]
 
 [dependencies]
 email_address = { version = "0.2.9", default-features = false, optional = true }
@@ -25,6 +26,7 @@ indexmap = { version = "2.12.0", optional = true }
 regex = { workspace = true, optional = true }
 serde = { workspace = true, features = ["derive"], optional = true }
 url = { version = "2.5.7", optional = true }
+utoipa = { workspace = true, optional = true }
 
 [dev-dependencies]
 pretty_assertions = "1.4.1"
diff --git a/packages/fortifier/src/lib.rs b/packages/fortifier/src/lib.rs
@@ -10,3 +10,12 @@ pub use validations::*;
 
 #[cfg(feature = "macros")]
 pub use fortifier_macros::*;
+
+#[doc(hidden)]
+pub mod external {
+    #[cfg(feature = "serde")]
+    pub use serde;
+
+    #[cfg(feature = "utoipa")]
+    pub use utoipa;
+}
diff --git a/packages/fortifier/src/validate.rs b/packages/fortifier/src/validate.rs
@@ -7,6 +7,7 @@ use std::{
 /// Validation errors.
 #[derive(Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct ValidationErrors<E>(Vec<E>);
 
 impl<E: Debug> Display for ValidationErrors<E> {
diff --git a/packages/fortifier/src/validations/email.rs b/packages/fortifier/src/validations/email.rs
diff --git a/packages/fortifier/src/validations/length.rs b/packages/fortifier/src/validations/length.rs
diff --git a/packages/fortifier/src/validations/regex.rs b/packages/fortifier/src/validations/regex.rs
diff --git a/packages/fortifier/src/validations/url.rs b/packages/fortifier/src/validations/url.rs
diff --git a/packages/fortifier/tests/serde.rs b/packages/fortifier/tests/serde.rs
