#480 Docs for rest api

Cargo.toml

@@ -97,6 +97,8 @@ webauthn-rs = { version = "0.5", features = [
 ] }
 webauthn-rs-proto = "0.5"
 x25519-dalek = { version = "2.0", features = ["static_secrets"] }
+# openapi
+utoipa = { version = "4", features = ["axum_extras"] }
 
 [dev-dependencies]
 bytes = "1.6"

src/db/models/device.rs

@@ -9,6 +9,7 @@ use ipnetwork::IpNetwork;
 use model_derive::Model;
 use sqlx::{query, query_as, Error as SqlxError, FromRow, PgConnection, PgExecutor};
 use thiserror::Error;
+use utoipa::ToSchema;
 
 use super::{
     error::ModelError,
@@ -92,7 +93,7 @@ impl DeviceInfo {
 
 // helper struct which includes full device info
 // including network activity metadata
-#[derive(Serialize, Deserialize, Clone, Debug)]
+#[derive(Serialize, Deserialize, Clone, Debug, ToSchema)]
 pub struct UserDevice {
     #[serde(flatten)]
     pub device: Device,

src/db/models/mod.rs

@@ -22,6 +22,7 @@ pub mod wireguard;
 pub mod yubikey;
 
 use sqlx::{query_as, Error as SqlxError, PgConnection};
+use utoipa::ToSchema;
 
 use self::{
     device::UserDevice,
@@ -61,7 +62,7 @@ pub struct SecurityKey {
 }
 
 // Basic user info used in user list, etc.
-#[derive(Deserialize, Serialize, Debug, Clone)]
+#[derive(Deserialize, Serialize, Debug, Clone, ToSchema)]
 pub struct UserInfo {
     pub id: Option<i64>,
     pub username: String,
@@ -184,7 +185,7 @@ impl UserInfo {
 }
 
 // Full user info with related objects
-#[derive(Deserialize, Serialize, Debug)]
+#[derive(Deserialize, Serialize, Debug, ToSchema)]
 pub struct UserDetails {
     pub user: UserInfo,
     #[serde(default)]

src/db/models/wireguard.rs

@@ -12,6 +12,7 @@ use model_derive::Model;
 use rand_core::OsRng;
 use sqlx::{query_as, query_scalar, Error as SqlxError, FromRow, PgConnection, PgExecutor};
 use thiserror::Error;
+use utoipa::ToSchema;
 use x25519_dalek::{PublicKey, StaticSecret};
 
 use super::{
@@ -67,7 +68,7 @@ pub enum GatewayEvent {
 }
 
 /// Stores configuration required to setup a WireGuard network
-#[derive(Clone, Debug, Model, Deserialize, Serialize, PartialEq)]
+#[derive(Clone, Debug, Model, Deserialize, Serialize, PartialEq, ToSchema)]
 #[table(wireguard_network)]
 pub struct WireguardNetwork {
     pub id: Option<i64>,

src/error.rs

@@ -1,6 +1,7 @@
 use axum::http::StatusCode;
 use sqlx::error::Error as SqlxError;
 use thiserror::Error;
+use utoipa::ToSchema;
 
 use crate::{
     auth::failed_login::FailedLoginError,
@@ -14,7 +15,7 @@ use crate::{
 };
 
 /// Represents kinds of error that occurred
-#[derive(Debug, Error)]
+#[derive(Debug, Error, ToSchema)]
 pub enum WebError {
     #[error("GRPC error: {0}")]
     Grpc(String),

src/handlers/group.rs

@@ -4,6 +4,7 @@ use axum::{
 };
 use serde_json::json;
 use sqlx::query_as;
+use utoipa::ToSchema;
 
 use super::{ApiResponse, EditGroupInfo, GroupInfo, Username};
 use crate::{
@@ -15,7 +16,7 @@ use crate::{
     // ldap::utils::{ldap_add_user_to_group, ldap_modify_group, ldap_remove_user_from_group},
 };
 
-#[derive(Serialize)]
+#[derive(Serialize, ToSchema)]
 pub(crate) struct Groups {
     groups: Vec<String>,
 }
@@ -116,6 +117,14 @@ pub(crate) async fn list_groups_info(
 }
 
 /// GET: Retrieve all groups.
+#[utoipa::path(
+    get,
+    path = "/api/v1/group",
+    responses(
+        (status = 200, description = "Retrieve all groups.", body = Groups),
+        (status = 403, description = "Forbidden error: ...")
+    )
+)]
 pub(crate) async fn list_groups(
     _session: SessionInfo,
     State(appstate): State<AppState>,

src/handlers/mod.rs

@@ -4,6 +4,7 @@ use axum::{
     Json,
 };
 use serde_json::{json, Value};
+use utoipa::ToSchema;
 use webauthn_rs::prelude::RegisterPublicKeyCredential;
 
 #[cfg(feature = "wireguard")]
@@ -38,7 +39,7 @@ pub(crate) mod yubikey;
 pub(crate) static SESSION_COOKIE_NAME: &str = "defguard_session";
 static SIGN_IN_COOKIE_NAME: &str = "defguard_sign_in";
 
-#[derive(Default)]
+#[derive(Default, ToSchema)]
 pub struct ApiResponse {
     pub json: Value,
     pub status: StatusCode,
@@ -196,7 +197,7 @@ pub struct EditGroupInfo {
     pub members: Vec<String>,
 }
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
 pub struct Username {
     pub username: String,
 }
@@ -211,37 +212,37 @@ pub struct AddUserData {
     pub password: Option<String>,
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, ToSchema)]
 pub struct StartEnrollmentRequest {
     #[serde(default)]
     pub send_enrollment_notification: bool,
     pub email: Option<String>,
 }
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
 pub struct PasswordChangeSelf {
     pub old_password: String,
     pub new_password: String,
 }
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
 pub struct PasswordChange {
     pub new_password: String,
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, ToSchema)]
 pub struct WalletSignature {
     pub address: String,
     pub signature: String,
 }
 
-#[derive(Deserialize, Serialize)]
+#[derive(Deserialize, Serialize, ToSchema)]
 pub struct WalletChallenge {
     pub id: i64,
     pub message: String,
 }
 
-#[derive(Deserialize)]
+#[derive(Deserialize, ToSchema)]
 pub struct WalletChange {
     pub use_for_mfa: bool,
 }