fix: alerts OpenAPI docs (#5519)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **New Features**
- Enhanced alert listing query parameters with optional stream type and
name
	- Made page size and index optional in alert queries

- **Refactor**
- Simplified alert query structure by consolidating stream and
pagination parameters
	- Marked certain alert fields as read-only in schema generation

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

src/handler/http/models/alerts/mod.rs

@@ -26,6 +26,7 @@ use utoipa::ToSchema;
 #[derive(Clone, Debug, Serialize, Deserialize, ToSchema)]
 pub struct Alert {
     #[serde(default)]
+    #[schema(read_only)]
     pub id: Option<Ksuid>,
 
     #[serde(default)]
@@ -70,10 +71,12 @@ pub struct Alert {
 
     /// Time when alert was last triggered. Unix timestamp.
     #[serde(default)]
+    #[schema(read_only)]
     pub last_triggered_at: Option<i64>,
 
     /// Time when alert was last satisfied. Unix timestamp.
     #[serde(default)]
+    #[schema(read_only)]
     pub last_satisfied_at: Option<i64>,
 
     #[serde(default)]
@@ -81,9 +84,11 @@ pub struct Alert {
 
     /// Time when alert was last updated. Unix timestamp.
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[schema(read_only)]
     pub updated_at: Option<i64>,
 
     #[serde(default)]
+    #[schema(read_only)]
     pub last_edited_by: Option<String>,
 }
 

src/handler/http/models/alerts/requests.rs

@@ -38,55 +38,33 @@ pub struct UpdateAlertRequestBody(pub Alert);
 #[derive(Debug, Deserialize, utoipa::IntoParams)]
 #[into_params(style = Form, parameter_in = Query)]
 #[serde(rename_all = "snake_case")]
+#[into_params(rename_all = "snake_case")]
 pub struct ListAlertsQuery {
     /// Optional folder ID filter parameter.
     pub folder: Option<String>,
 
-    #[serde(flatten)]
-    pub stream: Option<ListAlertsQueryStreamParams>,
-
     /// Optional owner user filter parameter.
     pub owner: Option<String>,
 
     /// Optional enabled filter parameter.
     pub enabled: Option<bool>,
 
-    /// The optional page size and page index of results to retrieve.
-    #[serde(flatten)]
-    pub page: Option<ListAlertsQueryPageParams>,
-}
-
-/// Parameters for filtering by stream in the HTTP URL query component for
-/// listing alerts.
-///
-/// This structure is flattened inside [ListAlertsQuery] and is used to enforce
-/// the constraint that `stream_name` can only be provided when `stream_type` is
-/// also provided.
-#[derive(Debug, Deserialize, utoipa::IntoParams)]
-#[serde(rename_all = "snake_case")]
-pub struct ListAlertsQueryStreamParams {
-    /// Stream type filter parameter.
-    pub stream_type: StreamType,
-
-    /// Optional stream name filter parameter.
-    pub stream_name: Option<String>,
-}
-
-/// Parameters for requesting a specific page of results in the HTTP URL query
-/// component for listing alerts.
-///
-/// This structure is flattened inside [ListAlertsQuery] and is used to enforce
-/// the constraint that `page_idx` can only be provided when `page_size` is
-/// also provided.
-#[derive(Debug, Deserialize, utoipa::IntoParams)]
-#[serde(rename_all = "snake_case")]
-pub struct ListAlertsQueryPageParams {
     /// The optional number of alerts to retrieve. If not set then all alerts
     /// that match the query parameters will be returned.
-    pub page_size: u64,
+    pub page_size: Option<u64>,
 
     /// The optional page index. If not set then defaults to `0`.
+    ///
+    /// This parameter is only used if `page_size` is also set.
     pub page_idx: Option<u64>,
+
+    /// Optional stream type filter parameter.
+    pub stream_type: Option<StreamType>,
+
+    /// Optional stream name filter parameter.
+    ///
+    /// This parameter is only used if `stream_type` is also provided.
+    pub stream_name: Option<String>,
 }
 
 /// HTTP URL query component that contains parameters for enabling alerts.
@@ -115,20 +93,14 @@ impl ListAlertsQuery {
         meta_alerts::ListAlertsParams {
             org_id: org_id.to_string(),
             folder_id: self.folder,
-            stream_type_and_name: self.stream.map(
-                |ListAlertsQueryStreamParams {
-                     stream_type,
-                     stream_name,
-                 }| { (stream_type.into(), stream_name) },
-            ),
+            stream_type_and_name: self
+                .stream_type
+                .map(|stream_type| (stream_type.into(), self.stream_name)),
             enabled: self.enabled,
             owner: self.owner,
-            page_size_and_idx: self.page.map(
-                |ListAlertsQueryPageParams {
-                     page_size,
-                     page_idx,
-                 }| { (page_size, page_idx.unwrap_or(0)) },
-            ),
+            page_size_and_idx: self
+                .page_size
+                .map(|page_size| (page_size, self.page_idx.unwrap_or(0))),
         }
     }
 }