Add optional schemars (JsonSchema) derives to public models for API responses and OpenAPI generation

Cargo.toml

@@ -26,6 +26,10 @@ url = "^2.2"
 uuid = { version = "^1.0", features = ["serde"] }
 hex = "0.4.3"
 
+# Conditional schemars versions
+schemars09 = { package = "schemars", version = "0.9.0", optional = true, features = ["uuid1", "chrono04", "bigdecimal04"] }
+schemars = { version = "^1", optional = true, features = ["uuid1", "chrono04", "bigdecimal04"] }
+
 [dependencies.reqwest]
 version = "^0.12"
 default-features = false
@@ -41,6 +45,8 @@ axum07 = ["dep:axum_07", "dep:tower"]
 axum08 = ["dep:axum_08", "dep:tower"]
 actix4 = ["dep:actix-web"]
 __reqwest = ["reqwest/json", "reqwest/multipart"]
+schemars09 = ["dep:schemars09"]
+schemars1 = ["dep:schemars"]
 
 [lib]
 doctest = false

README.md

@@ -140,6 +140,31 @@ If you'd rather use a pure Rust TLS implementation rather than OpenSSL disable t
 propelauth = { version >= "0.12.1", features = ["rustls"], default-features = false }
 ```
 
+## JSON Schemas (schemars)
+
+This crate can optionally derive JSON Schemas for its request/response types using the schemars crate. This is useful if you want to automatically generate API documentation (e.g., OpenAPI) for endpoints that return or accept PropelAuth types, using libraries like aide.
+
+There are two feature flags to support both the 0.9 and 1.x lines of schemars:
+
+- schemars09 — enables schemars = 0.9.x compatibility
+- schemars-latest — enables schemars = 1.x compatibility
+
+Only enable one of these features at a time.
+
+Enabling schemars in your Cargo.toml:
+
+```toml
+# Choose one of the following feature flags
+propelauth = { version = "^0", features = ["schemars-latest"] }
+# or, if your project is still on schemars 0.9
+# propelauth = { version = "^0", features = ["schemars09"] }
+```
+
+What you get when enabled:
+
+- The crate's data models (for example: User, UserInOrg, CreateMagicLinkRequest, CreateAccessTokenResponse, and many others) will derive schemars::JsonSchema behind the selected feature flag.
+- You can then use those types with OpenAPI generators that rely on schemars, such as aide, utoipa-with-schemars adapter, or custom schema generation code.
+
 ## Other
 
 After initializing `auth`, you can verify [access tokens](https://docs.propelauth.com/guides-and-examples/guides/access-tokens) by passing in the Authorization header (formatted `Bearer TOKEN`):

src/apis/access_token_service_api.rs

@@ -3,13 +3,23 @@ use reqwest;
 use super::{configuration, Error};
 use crate::{apis::ResponseContent, propelauth::auth::AUTH_HOSTNAME_HEADER};
 
+#[cfg(feature = "schemars09")]
+use {
+    std::convert::TryFrom,
+    schemars09 as schemars,
+};
+#[cfg(any(feature = "schemars09", feature = "schemars1"))]
+use schemars::JsonSchema;
+
 /// struct for passing parameters to the method [`create_access_token`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct CreateAccessTokenParams {
     pub create_access_token_request: crate::models::CreateAccessTokenRequest,
 }
 
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct CreateAccessTokenV2Params {
     pub create_access_token_request: crate::models::CreateAccessTokenV2Request,
 }

src/apis/api_key_service_api.rs

@@ -11,8 +11,18 @@ use crate::{apis::ResponseContent, propelauth::auth::AUTH_HOSTNAME_HEADER};
 
 use super::{configuration, Error};
 
+#[cfg(feature = "schemars09")]
+use {
+    std::convert::TryFrom,
+    schemars09 as schemars,
+};
+#[cfg(any(feature = "schemars09", feature = "schemars1"))]
+use schemars::JsonSchema;
+
+
 /// struct for passing parameters to the method [`fetch_api_keys`, `fetch_archived_api_keys`]
 #[derive(Clone, Debug, Default, Serialize)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct ApiKeyQueryParams {
     pub user_id: Option<String>,
     pub user_email: Option<String>,
@@ -23,6 +33,7 @@ pub struct ApiKeyQueryParams {
 
 /// struct for passing parameters to the method [`create_api_key`]
 #[derive(Clone, Debug, Default, Serialize)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct CreateApiKeyParams {
     pub expires_at_seconds: Option<i64>,
     pub metadata: Option<serde_json::Value>,
@@ -32,6 +43,7 @@ pub struct CreateApiKeyParams {
 
 /// struct for passing parameters to the method [`update_api_key`]
 #[derive(Clone, Debug, Default, Serialize)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct UpdateApiKeyParams {
     pub expires_at_seconds: Option<i64>,
     pub metadata: Option<serde_json::Value>,
@@ -40,6 +52,7 @@ pub struct UpdateApiKeyParams {
 
 /// struct for passing parameters to the method [`validate_api_key`]
 #[derive(Clone, Debug, Default, Serialize)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct ValidateApiKeyParams {
     pub api_key_token: String,
 }

src/apis/configuration.rs

@@ -10,6 +10,7 @@
 
 use reqwest;
 
+
 #[derive(Debug, Clone)]
 pub struct Configuration {
     pub base_path: String,

src/apis/org_service_api.rs

@@ -15,51 +15,67 @@ use crate::apis::ResponseContent;
 use crate::models::{FetchOrgOrderBy, SuccessfulResponse};
 use crate::propelauth::auth::AUTH_HOSTNAME_HEADER;
 
+#[cfg(feature = "schemars09")]
+use {
+    std::convert::TryFrom,
+    schemars09 as schemars,
+};
+#[cfg(any(feature = "schemars09", feature = "schemars1"))]
+use schemars::JsonSchema;
+
 /// struct for passing parameters to the method [`add_user_to_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct AddUserToOrgParams {
     pub add_user_to_org_request: crate::models::AddUserToOrgRequest,
 }
 
 /// struct for passing parameters to the method [`allow_org_to_enable_saml`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct AllowOrgToEnableSamlParams {
     pub org_id: String,
 }
 
 /// struct for passing parameters to the method [`change_user_role_in_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct ChangeUserRoleInOrgParams {
     pub change_user_role_in_org_request: crate::models::ChangeUserRoleInOrgRequest,
 }
 
 /// struct for passing parameters to the method [`create_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct CreateOrgParams {
     pub create_org_request: crate::models::CreateOrgRequest,
 }
 
 /// struct for passing parameters to the method [`disallow_saml`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct DisallowSamlParams {
     pub org_id: String,
 }
 
 /// struct for passing parameters to the method [`create_saml_connection_link`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct CreateSamlConnectionLinkParams {
     pub org_id: String,
     pub expires_in_seconds: Option<i64>,
 }
 
 /// struct for passing parameters to the method [`fetch_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchOrgParams {
     pub org_id: String,
 }
 
 /// struct for passing parameters to the method [`fetch_orgs_by_query`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchOrgsByQueryParams {
     pub page_size: Option<i64>,
     pub page_number: Option<i64>,
@@ -71,6 +87,7 @@ pub struct FetchOrgsByQueryParams {
 
 /// struct for passing parameters to the method [`fetch_pending_invites`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchPendingInvitesParams {
     pub page_size: Option<i64>,
     pub page_number: Option<i64>,
@@ -79,6 +96,7 @@ pub struct FetchPendingInvitesParams {
 
 /// struct for passing parameters to the method [`fetch_users_in_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUsersInOrgParams {
     pub org_id: String,
     pub page_size: Option<i64>,
@@ -90,32 +108,37 @@ pub struct FetchUsersInOrgParams {
 
 /// struct for passing parameters to the method [`remove_user_from_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct RemoveUserFromOrgParams {
     pub remove_user_from_org_request: crate::models::RemoveUserFromOrgRequest,
 }
 
 /// struct for passing parameters to the method [`update_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct UpdateOrgParams {
     pub org_id: String,
     pub update_org_request: crate::models::UpdateOrgRequest,
 }
 
 /// struct for passing parameters to the method [`subscribe_org_to_role_mapping`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct SubscribeOrgToRoleMappingParams {
     pub org_id: String,
     pub update_org_request: crate::models::SubscribeOrgToRoleMappingRequest,
 }
 
 /// struct for passing parameters to the method [`delete_org`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct DeleteOrgParams {
     pub org_id: String,
 }
 
 /// struct for passing parameters to the method [`revoke_pending_org_invite`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct RevokePendingOrgInviteParams {
     pub revoke_pending_org_invite_request: crate::models::RevokePendingOrgInviteRequest,
 }

src/apis/user_service_api.rs

@@ -15,44 +15,59 @@ use crate::models::{FetchUsersOrderBy, ResendEmailConfirmationRequest};
 use crate::propelauth::auth::AUTH_HOSTNAME_HEADER;
 use crate::{apis::ResponseContent, models::InviteUserToOrgRequest};
 
+#[cfg(feature = "schemars09")]
+use {
+    std::convert::TryFrom,
+    schemars09 as schemars,
+};
+#[cfg(any(feature = "schemars09", feature = "schemars1"))]
+use schemars::JsonSchema;
+
 /// struct for passing parameters to the method [`create_magic_link`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct CreateMagicLinkParams {
     pub create_magic_link_request: crate::models::CreateMagicLinkRequest,
 }
 
 /// struct for passing parameters to the method [`create_user`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct CreateUserParams {
     pub create_user_request: crate::models::CreateUserRequest,
 }
 
 /// struct for passing parameters to the method [`delete_user`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct DeleteUserParams {
     pub user_id: String,
 }
 
 /// struct for passing parameters to the method [`disable_user`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct DisableUserParams {
     pub user_id: String,
 }
 
 /// struct for passing parameters to the method [`disable_user2fa`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct DisableUser2faParams {
     pub user_id: String,
 }
 
 /// struct for passing parameters to the method [`enable_user`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct EnableUserParams {
     pub user_id: String,
 }
 
 /// struct for passing parameters to the method [`fetch_user_by_email`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUserByEmailParams {
     pub email: String,
     /// Defaults to false
@@ -61,6 +76,7 @@ pub struct FetchUserByEmailParams {
 
 /// struct for passing parameters to the method [`fetch_user_by_id`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUserByIdParams {
     pub user_id: String,
     /// Defaults to false
@@ -69,6 +85,7 @@ pub struct FetchUserByIdParams {
 
 /// struct for passing parameters to the method [`fetch_user_by_username`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUserByUsernameParams {
     pub username: String,
     /// Defaults to false
@@ -77,6 +94,7 @@ pub struct FetchUserByUsernameParams {
 
 /// struct for passing parameters to the method [`fetch_users_by_emails`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUsersByEmailsParams {
     pub emails_query: crate::models::EmailsQuery,
     /// Defaults to false
@@ -85,6 +103,7 @@ pub struct FetchUsersByEmailsParams {
 
 /// struct for passing parameters to the method [`fetch_users_by_ids`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUsersByIdsParams {
     pub user_ids_query: crate::models::UserIdsQuery,
     /// Defaults to false
@@ -93,6 +112,7 @@ pub struct FetchUsersByIdsParams {
 
 /// struct for passing parameters to the method [`fetch_users_by_query`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUsersByQueryParams {
     pub page_size: Option<i64>,
     pub page_number: Option<i64>,
@@ -104,6 +124,7 @@ pub struct FetchUsersByQueryParams {
 
 /// struct for passing parameters to the method [`fetch_users_by_usernames`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct FetchUsersByUsernamesParams {
     pub usernames_query: crate::models::UsernamesQuery,
     /// Defaults to false
@@ -112,32 +133,37 @@ pub struct FetchUsersByUsernamesParams {
 
 /// struct for passing parameters to the method [`migrate_user`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct MigrateUserParams {
     pub migrate_user_request: crate::models::MigrateUserRequest,
 }
 
 /// struct for passing parameters to the method [`migrate_user_password`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct MigrateUserPasswordParams {
     pub migrate_user_password_request: crate::models::MigrateUserPasswordRequest,
 }
 
 /// struct for passing parameters to the method [`update_user_email`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct UpdateUserEmailParams {
     pub user_id: String,
     pub update_email_request: crate::models::UpdateEmailRequest,
 }
 
 /// struct for passing parameters to the method [`update_user_metadata`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct UpdateUserMetadataParams {
     pub user_id: String,
     pub update_metadata_request: crate::models::UpdateMetadataRequest,
 }
 
 /// struct for passing parameters to the method [`update_user_password`]
 #[derive(Clone, Debug, Default)]
+#[cfg_attr(any(feature = "schemars09", feature = "schemars1"), derive(JsonSchema))]
 pub struct UpdateUserPasswordParams {
     pub user_id: String,
     pub update_password_request: crate::models::UpdatePasswordRequest,