admin api: add openapi spec for admin token management functions

src/api/admin/api.rs

@@ -298,15 +298,9 @@ pub struct ConnectNodeResponse {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ListAdminTokensRequest;
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct ListAdminTokensResponse(pub Vec<GetAdminTokenInfoResponse>);
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct ListAdminTokensResponseItem {
-	pub id: String,
-	pub name: String,
-}
-
 // ---- GetAdminTokenInfo ----
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -315,13 +309,21 @@ pub struct GetAdminTokenInfoRequest {
 	pub search: Option<String>,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct GetAdminTokenInfoResponse {
+	/// Identifier of the admin token (which is also a prefix of the full bearer token)
 	pub id: String,
+	/// Name of the admin API token
 	pub name: String,
+	/// Expiration time and date, formatted according to RFC 3339
+	#[schema(value_type = Option<String>)]
 	pub expiration: Option<chrono::DateTime<chrono::Utc>>,
+	/// Whether this admin token is expired already
 	pub expired: bool,
+	/// Scope of the admin API token, a list of admin endpoint names (such as
+	/// `GetClusterStatus`, etc), or the special value `*` to allow all
+	/// admin endpoints
 	pub scope: Vec<String>,
 }
 
@@ -330,9 +332,12 @@ pub struct GetAdminTokenInfoResponse {
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct CreateAdminTokenRequest(pub UpdateAdminTokenRequestBody);
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct CreateAdminTokenResponse {
+	/// The secret bearer token. **CAUTION:** This token will be shown only
+	/// ONCE, so this value MUST be remembered somewhere, or the token
+	/// will be unusable.
 	pub secret_token: String,
 	#[serde(flatten)]
 	pub info: GetAdminTokenInfoResponse,
@@ -346,15 +351,23 @@ pub struct UpdateAdminTokenRequest {
 	pub body: UpdateAdminTokenRequestBody,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 #[serde(rename_all = "camelCase")]
 pub struct UpdateAdminTokenRequestBody {
+	/// Name of the admin API token
 	pub name: Option<String>,
+	/// Expiration time and date, formatted according to RFC 3339
+	#[schema(value_type = Option<String>)]
 	pub expiration: Option<chrono::DateTime<chrono::Utc>>,
+	/// Scope of the admin API token, a list of admin endpoint names (such as
+	/// `GetClusterStatus`, etc), or the special value `*` to allow all
+	/// admin endpoints. **WARNING:** Granting a scope of `CreateAdminToken` or
+	/// `UpdateAdminToken` trivially allows for privilege escalation, and is thus
+	/// functionnally equivalent to granting a scope of `*`.
 	pub scope: Option<Vec<String>>,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
 pub struct UpdateAdminTokenResponse(pub GetAdminTokenInfoResponse);
 
 // ---- DeleteAdminToken ----

src/api/admin/openapi.rs

@@ -66,6 +66,82 @@ fn GetClusterStatistics() -> () {}
 )]
 fn ConnectClusterNodes() -> () {}
 
+// **********************************************
+//      Admin API token operations
+// **********************************************
+
+#[utoipa::path(get,
+    path = "/v2/ListAdminTokens",
+    tag = "Admin API token",
+    description = "Returns all admin API tokens in the cluster.",
+	responses(
+            (status = 200, description = "Returns info about all admin API tokens", body = ListAdminTokensResponse),
+            (status = 500, description = "Internal server error")
+        ),
+)]
+fn ListAdminTokens() -> () {}
+
+#[utoipa::path(get,
+    path = "/v2/GetAdminTokenInfo",
+    tag = "Admin API token",
+    description = "
+Return information about a specific admin API token.
+You can search by specifying the exact token identifier (`id`) or by specifying a pattern (`search`).
+    ",
+    params(
+        ("id", description = "Admin API token ID"),
+        ("search", description = "Partial token ID or name to search for"),
+    ),
+	responses(
+            (status = 200, description = "Information about the admin token", body = GetAdminTokenInfoResponse),
+            (status = 500, description = "Internal server error")
+        ),
+)]
+fn GetAdminTokenInfo() -> () {}
+
+#[utoipa::path(post,
+    path = "/v2/CreateAdminToken",
+    tag = "Admin API token",
+    description = "Creates a new admin API token",
+    request_body = UpdateAdminTokenRequestBody,
+	responses(
+            (status = 200, description = "Admin token has been created", body = CreateAdminTokenResponse),
+            (status = 500, description = "Internal server error")
+        ),
+)]
+fn CreateAdminToken() -> () {}
+
+#[utoipa::path(post,
+    path = "/v2/UpdateAdminToken",
+    tag = "Admin API token",
+    description = "
+Updates information about the specified admin API token.
+    ",
+    request_body = UpdateAdminTokenRequestBody,
+    params(
+        ("id", description = "Admin API token ID"),
+    ),
+	responses(
+            (status = 200, description = "Admin token has been updated", body = UpdateAdminTokenResponse),
+            (status = 500, description = "Internal server error")
+        ),
+)]
+fn UpdateAdminToken() -> () {}
+
+#[utoipa::path(post,
+    path = "/v2/DeleteAdminToken",
+    tag = "Admin API token",
+    description = "Delete an admin API token from the cluster, revoking all its permissions.",
+    params(
+        ("id", description = "Admin API token ID"),
+    ),
+	responses(
+            (status = 200, description = "Admin token has been deleted"),
+            (status = 500, description = "Internal server error")
+        ),
+)]
+fn DeleteAdminToken() -> () {}
+
 // **********************************************
 //      Layout operations
 // **********************************************
@@ -723,6 +799,12 @@ impl Modify for SecurityAddon {
         GetClusterStatus,
         GetClusterStatistics,
         ConnectClusterNodes,
+        // Admin token operations
+        ListAdminTokens,
+        GetAdminTokenInfo,
+        CreateAdminToken,
+        UpdateAdminToken,
+        DeleteAdminToken,
         // Layout operations
         GetClusterLayout,
         GetClusterLayoutHistory,