Extend OpenAPI docs with OpenID providers

crates/defguard_core/src/enterprise/handlers/openid_providers.rs

@@ -54,8 +54,11 @@ pub struct AddProviderData {
 #[utoipa::path(
     post,
     path = "/api/v1/openid/provider",
+    params(
+        ("data" = AddProviderData, Path, description = "OpenID provider data",)
+    ),
     responses(
-        (status = CREATED, description = "Add OpenID provider", body = [AddProviderData]),
+        (status = CREATED, description = "Add OpenID provider"),
     ),
 )]
 pub(crate) async fn add_openid_provider(
@@ -194,7 +197,7 @@ pub(crate) async fn add_openid_provider(
 /// # Returns
 /// - HTTP Status "OK" on success.
 #[utoipa::path(
-    put,
+    get,
     path = "/api/v1/openid/provider/{name}",
     responses(
         (status = OK, description = "Get OpenID provider"),
@@ -240,7 +243,7 @@ pub(crate) async fn get_openid_provider(
 /// # Returns
 /// - HTTP Status "OK" on success.
 #[utoipa::path(
-    get,
+    delete,
     path = "/api/v1/openid/provider/{name}",
     responses(
         (status = OK, description = "Delete OpenID provider"),

crates/defguard_core/src/handlers/auth.rs

@@ -130,9 +130,19 @@ pub(crate) async fn create_session(
     }
 }
 
-/// For successful login, return:
+/// Authenticate a user.
+///
+/// # For successful login, returns:
 /// * 200 with MFA disabled
 /// * 201 with MFA enabled when additional authentication factor is required
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth",
+    responses(
+        (status = OK, description = "User authenticated"),
+        (status = CREATED, description = "User authenticated, but an additional authentication factor is required"),
+    ),
+)]
 pub(crate) async fn authenticate(
     cookies: CookieJar,
     mut private_cookies: PrivateCookieJar,
@@ -298,7 +308,14 @@ pub(crate) async fn authenticate(
 }
 
 /// Logout - forget the session cookie.
-pub async fn logout(
+#[utoipa::path(
+    post,
+    path = "/api/v1/auth/logout",
+    responses(
+        (status = OK, description = "User logged out"),
+    ),
+)]
+pub(crate) async fn logout(
     cookies: CookieJar,
     SessionExtractor(session): SessionExtractor,
     user_agent: TypedHeader<UserAgent>,

crates/defguard_core/src/handlers/mod.rs

@@ -221,7 +221,7 @@ impl IntoResponse for ApiResponse {
 
 pub type ApiResult = Result<ApiResponse, WebError>;
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
 pub struct Auth {
     username: String,
     password: String,

crates/defguard_core/src/lib.rs

@@ -67,10 +67,7 @@ use tower_http::{
     trace::{DefaultOnResponse, TraceLayer},
 };
 use tracing::Level;
-use utoipa::{
-    Modify, OpenApi,
-    openapi::security::{ApiKey, ApiKeyValue, SecurityScheme},
-};
+use utoipa::OpenApi;
 use utoipa_swagger_ui::SwaggerUi;
 
 use self::{
@@ -188,149 +185,7 @@ static PHONE_NUMBER_REGEX: LazyLock<Regex> = LazyLock::new(|| {
         .expect("Failed to parse phone number regex")
 });
 
-mod openapi {
-    use defguard_common::{
-        db::models::{
-            Device,
-            device::{AddDevice, ModifyDevice, UserDevice},
-        },
-        types::user_info::UserInfo,
-    };
-    use handlers::{
-        ApiResponse, EditGroupInfo, GroupInfo, PasswordChange, PasswordChangeSelf,
-        SESSION_COOKIE_NAME, StartEnrollmentRequest, Username,
-        group::{self, BulkAssignToGroupsRequest, Groups},
-        user, wireguard as device, wireguard as network,
-        wireguard::AddDeviceResult,
-    };
-    use utoipa::{
-        OpenApi,
-        openapi::security::{HttpAuthScheme, HttpBuilder},
-    };
-
-    use super::*;
-    use crate::{enterprise::snat::handlers as snat, error::WebError, handlers::user::UserDetails};
-
-    #[derive(OpenApi)]
-    #[openapi(
-        modifiers(&SecurityAddon),
-        paths(
-            // /user
-            user::list_users,
-            user::get_user,
-            user::add_user,
-            user::start_enrollment,
-            user::start_remote_desktop_configuration,
-            user::username_available,
-            user::modify_user,
-            user::delete_user,
-            user::change_self_password,
-            user::change_password,
-            user::reset_password,
-            user::delete_security_key,
-            user::me,
-            user::delete_authorized_app,
-            // /group
-            group::bulk_assign_to_groups,
-            group::list_groups_info,
-            group::list_groups,
-            group::get_group,
-            group::create_group,
-            group::modify_group,
-            group::delete_group,
-            group::add_group_member,
-            group::remove_group_member,
-            // /device
-            device::add_device,
-            device::modify_device,
-            device::get_device,
-            device::delete_device,
-            device::list_devices,
-            device::list_user_devices,
-            // /network
-            network::create_network,
-            network::modify_network,
-            network::delete_network,
-            network::list_networks,
-            network::network_details,
-            // /network/{location_id}/snat
-			snat::list_snat_bindings,
-			snat::create_snat_binding,
-			snat::modify_snat_binding,
-			snat::delete_snat_binding,
-        ),
-        components(
-            schemas(
-                ApiResponse, UserInfo, UserDetails, UserDevice, Groups, Username, StartEnrollmentRequest, PasswordChangeSelf, PasswordChange, AddDevice, AddDeviceResult, Device, ModifyDevice, BulkAssignToGroupsRequest, GroupInfo, EditGroupInfo, WebError
-            ),
-        ),
-        tags(
-            (name = "user", description = "
-### Endpoints for managing users
-Available actions:
-- list all users
-- disable/enable user
-- CRUD mechanism for handling users
-- operations on security key and authorized app
-- change user password.
-- start remote desktop configuratiion
-- trigger enrollment process
-            "),
-            (name = "group", description = "
-### Endpoints for managing groups
-Available actions:
-- list all groups
-- CRUD mechanism for handling groups
-- add or delete a group member
-- remove group
-- bulk assign users to groups
-            "),
-            (name = "device", description = "
-### Endpoints for managing devices
-
-Available actions:
-- list all devices or user devices
-- CRUD mechanism for handling devices.
-            "),
-            (name = "network", description = "
-### Endpoints that allow to control your networks.
-
-Available actions:
-- list all wireguard networks
-- CRUD mechanism for handling devices.
-            "),
-            (name = "SNAT", description = "
-### Endpoints that allow you to control user SNAT bindings for your locations.
-
-Available actions:
-- list all SNAT bindings
-- create new SNAT binding
-- modify SNAT binding
-- delete SNAT binding
-            "),
-        )
-    )]
-    pub struct ApiDoc;
-
-    struct SecurityAddon;
-
-    impl Modify for SecurityAddon {
-        fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
-            if let Some(components) = openapi.components.as_mut() {
-                // session cookie auth
-                components.add_security_scheme(
-                    "cookie",
-                    SecurityScheme::ApiKey(ApiKey::Cookie(ApiKeyValue::new(SESSION_COOKIE_NAME))),
-                );
-                // API token auth
-                components.add_security_scheme(
-                    "api_token",
-                    SecurityScheme::Http(HttpBuilder::new().scheme(HttpAuthScheme::Bearer).build()),
-                );
-            }
-        }
-    }
-}
+mod openapi;
 
 /// Simple health-check.
 async fn health_check() -> &'static str {